Pbip Project

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:

.pbip                    # Project pointer file
├── .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/
│       │   └── .tmdl
│       └── expressions.tmdl
├── .Report/             # Report folder
│   ├── definition.pbir               # Report pointer
│   ├── report.json                   # Report configuration
│   └── definition/                   # Report definition files
│       ├── pages/
│       │   └── /
│       │       └── page.json
│       └── ...
└── .pbi/                             # Local settings (gitignored)
    └── localSettings.json

Creating a New PBIP Project

Step 1: Create the Project Pointer File

Create .pbip:

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

Step 2: Create the Semantic Model Folder

Create .SemanticModel/definition.pbism:

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

Step 3: Create Core TMDL Files

Create .SemanticModel/definition/database.tmdl:

database ''
	compatibilityLevel: 1567

Create .SemanticModel/definition/model.tmdl:

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

Step 4: Create the Report Folder

Create .Report/definition.pbir:

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

Create .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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kpbray
• Source: kpbray/power-bi-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.