pbip-project

name	pbip-project
description	Creates and manages Power BI Desktop Project (PBIP) structure. Use when starting new Power BI projects, setting up folder structure, or configuring project files.

PBIP Project Skill

This skill helps create and manage Power BI Desktop Project (PBIP) structure for source control-friendly Power BI development.

When to Use This Skill

• Starting a new Power BI project from scratch
• Converting an existing concept into a PBIP structure
• Setting up the folder structure for semantic models and reports
• Creating pointer files (.pbip, .pbism, .pbir)
• Configuring project-level settings

PBIP Project Structure

A complete PBIP project has this structure:

<ProjectName>.pbip                    # Project pointer file
├── <ProjectName>.SemanticModel/      # Semantic model folder
│   ├── definition.pbism              # Semantic model pointer
│   ├── model.bim                     # Model metadata (auto-generated)
│   └── definition/                   # TMDL files
│       ├── database.tmdl
│       ├── model.tmdl
│       ├── relationships.tmdl
│       ├── tables/
│       │   └── <TableName>.tmdl
│       └── expressions.tmdl
├── <ProjectName>.Report/             # Report folder
│   ├── definition.pbir               # Report pointer
│   ├── report.json                   # Report configuration
│   └── definition/                   # Report definition files
│       ├── pages/
│       │   └── <PageId>/
│       │       └── page.json
│       └── ...
└── .pbi/                             # Local settings (gitignored)
    └── localSettings.json

Creating a New PBIP Project

Step 1: Create the Project Pointer File

Create <ProjectName>.pbip:

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

Step 2: Create the Semantic Model Folder

Create <ProjectName>.SemanticModel/definition.pbism:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": null,
    "byConnection": null
  }
}

Step 3: Create Core TMDL Files

Create <ProjectName>.SemanticModel/definition/database.tmdl:

database '<ProjectName>'
	compatibilityLevel: 1567

Create <ProjectName>.SemanticModel/definition/model.tmdl:

model Model
	culture: en-US
	defaultPowerBIDataSourceVersion: powerBI_V3
	discourageImplicitMeasures: true
	sourceQueryCulture: en-US

Step 4: Create the Report Folder

Create <ProjectName>.Report/definition.pbir:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": {
      "path": "../<ProjectName>.SemanticModel"
    },
    "byConnection": null
  }
}

Create <ProjectName>.Report/report.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  "config": {
    "version": 5,
    "defaultDrillFilterOtherVisuals": true
  },
  "objects": {}
}

File Format Requirements

Encoding

• All text files MUST be UTF-8 without BOM
• JSON files use 2-space indentation
• TMDL files use tab indentation

Line Endings

• Use LF (Unix-style) line endings for cross-platform compatibility
• Configure .gitattributes for consistent line endings:

*.tmdl text eol=lf
*.json text eol=lf
*.pbip text eol=lf
*.pbism text eol=lf
*.pbir text eol=lf

Git Configuration

Recommended .gitignore

# Local Power BI settings (contains user-specific paths)
.pbi/
**/localSettings.json

# Cache files
*.abf
**/cache.abf

# Temporary files
*.tmp
~$*

Recommended .gitattributes

# Ensure consistent line endings
*.tmdl text eol=lf
*.json text eol=lf
*.pbip text eol=lf
*.pbism text eol=lf
*.pbir text eol=lf

# Treat binary files appropriately
*.abf binary
*.pbix binary

Naming Conventions

Item	Convention	Example
Project name	PascalCase	SalesAnalytics
Folder names	Match project name	SalesAnalytics.SemanticModel
TMDL files	lowercase with hyphens	date-table.tmdl
Page folders	GUID format	ReportSection1a2b3c4d

Boundaries and Constraints

DO

• Always create files with UTF-8 encoding (no BOM)
• Always include compatibilityLevel in database.tmdl
• Always set discourageImplicitMeasures: true in model.tmdl
• Create .gitignore to exclude local settings
• Use relative paths in pointer files

DO NOT

• Never modify .pbi/localSettings.json - this is user-specific
• Never commit cache.abf files
• Never hardcode absolute file paths
• Never include credentials in source files

Workflow Integration

After creating the project structure:

1. Add tables - Use the semantic-model skill to add tables and relationships
2. Add measures - Use the dax skill to create measures
3. Create visuals - Use the report-visuals skill to build reports
4. Validate - Use the best-practices skill to check quality

Opening in Power BI Desktop

1. Open Power BI Desktop
2. File > Open report
3. Select the .pbip file
4. Power BI will load the project from source files

Common Issues

"Cannot find semantic model"

• Verify the path in definition.pbir points to the correct semantic model folder
• Ensure definition.pbism exists in the semantic model folder

"Invalid TMDL syntax"

• Check for proper indentation (tabs for TMDL)
• Verify quotes match the expected style (single quotes for identifiers)
• Ensure compatibility level is supported

"Report won't load"

• Check that report.json has valid JSON syntax
• Verify the schema reference is correct
• Ensure page folders contain valid page.json files