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

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