lukasreese/powerbi-claude-skills/pbir-report-builder

PBIR Report Builder

Add pages and visuals to existing Power BI PBIP projects by writing PBIR (Enhanced Report Format) JSON files directly into the project folder structure.

Critical: Hybrid Approach (Do NOT Create PBIP From Scratch)

NEVER create an entire PBIP project from scratch. Power BI Desktop generates boilerplate files (report.json, .platform, version.json, theme packages, settings) with version-specific schema references, real GUIDs, and internal settings that are impractical to replicate manually.

The correct workflow:

1. User creates a blank PBIP — open Power BI Desktop, connect to the data source, save as PBIP format. This generates all boilerplate correctly.
2. Semantic model measures — use powerbi-modeling-mcp if Desktop is running, OR write directly to TMDL files if Desktop is closed (see "Adding Measures When Desktop Is Closed" below).
3. This skill adds pages and visuals — write PBIR JSON files into the existing .Report/definition/ folder to create report pages with visuals.

Why not from scratch? The report.json file contains Desktop-version-specific theme references (e.g., CY26SU02 with nested version objects), resource packages, 6+ report settings, and the .platform files need real UUIDs. These change between Desktop versions and cannot be reliably generated.

PBIP File Structure (for reference — user creates this by saving)

ProjectName.pbip                           ← entry point (Desktop creates)
ProjectName.Report/
  .platform                                ← Desktop creates (Report type, UUID)
  definition.pbir                          ← Desktop creates (links to semantic model)
  definition/
    report.json                            ← Desktop creates (theme, settings)
    version.json                           ← Desktop creates
    pages/
      pages.json                           ← WE MODIFY (add page to pageOrder)
      pg01Overview/                        ← WE CREATE
        page.json                          ← WE CREATE
        visuals/
          v01KpiSales/visual.json          ← WE CREATE
ProjectName.SemanticModel/
  .platform                                ← Desktop creates (SemanticModel type, UUID)
  definition.pbism                         ← Desktop creates (NOT definition.tmdl!)
  definition/
    database.tmdl                          ← Desktop creates (compatibilityLevel: 1600)
    model.tmdl                             ← Desktop creates or MCP server manages
    tables/*.tmdl                          ← MCP server manages

Key learning: The semantic model entry point is definition.pbism (a JSON file), NOT definition.tmdl. TMDL files go inside the definition/ subfolder.

References (Self-Contained)

All reference material is bundled inside this skill at references/:

Reference docs:

• references/visual-types.md — all 35+ visual type identifiers and query roles
• references/field-references.md — column/measure binding patterns, aggregation codes, conditional formatting
• references/formatting-objects.md — container/visual/page formatting JSON patterns
• references/folder-structure.md — annotated PBIP/PBIR/TMDL folder tree
• references/page-naming.md — readable naming convention (pg##/v## rules)

JSON templates (ready-to-use):

• references/json-templates/card-kpi.json — KPI card with CY, PY, YoY%, conditional color
• references/json-templates/clustered-column.json — vertical bar chart
• references/json-templates/clustered-bar.json — horizontal bar chart
• references/json-templates/line-chart.json — line trend over time
• references/json-templates/combo-chart.json — column + line combo
• references/json-templates/table.json — table with multiple columns/measures
• references/json-templates/matrix.json — pivot table with rows/columns/values
• references/json-templates/slicer.json — slicer dropdown
• references/json-templates/donut.json — donut/pie chart
• references/json-templates/page-standard.json — standard page definition
• references/json-templates/page-drillthrough.json — drillthrough page
• references/json-templates/report-settings.json — report-level settings

Complete examples (start here for new users):

• references/examples/kpi-dashboard-example.md — full working example: 4 KPI cards + bar chart + line chart, complete Node.js script, DAX measures, layout grid
• references/examples/card-kpi-with-yoy.md — KPI card with conditional YoY badge — cardVisual with prior-year reference row, custom label ("vs. PY:"), and green/red % badge driven by DAX color measures. Includes full referenceLabelDetail conditional formatting pattern, required DAX measures, complete JSON template with placeholders, and community contribution guide.

JSON schemas (Microsoft originals):

• references/json-schemas/ — local copies of all PBIR schemas for offline validation

IBCS Visuals (integrated):

• references/ibcs-visuals/IBCS-REFERENCE.md — full IBCS workflow, template selection guide, generation steps
• references/ibcs-visuals/references/ibcs-colors.md — IBCS color palette (actual, comparison, positive, negative)
• references/ibcs-visuals/references/ibcs-dax-measures.md — 15 DAX measure templates for column variance
• references/ibcs-visuals/references/ibcs-svg-measures.md — SVG measure templates for table visuals
• references/ibcs-visuals/references/ibcs-column-variance.md — combo chart visual.json pattern
• references/ibcs-visuals/references/ibcs-bar-variance.md — bar chart with NativeVisualCalculation pattern
• references/ibcs-visuals/references/ibcs-table-simple.md — pivot table with SVG variance bars
• references/ibcs-visuals/references/ibcs-table-full.md — full SVG table (AC, PY bars + variance)

For IBCS visuals, read references/ibcs-visuals/IBCS-REFERENCE.md for the full workflow and template selection guide.

Read the relevant template file when building a visual type you haven't used recently.

How It Works

Step 0: Prerequisites

Before using this skill, verify:

1. A PBIP project already exists — user must have saved a .pbip from Power BI Desktop
2. The semantic model is connected — the .SemanticModel/ folder has data tables with columns
3. Measures exist or can be created — either already in the model, creatable via MCP, or writable to TMDL
4. Power BI Desktop is CLOSED — files cannot be written while Desktop has the project open

If the user doesn't have a PBIP yet, instruct them to:

1. Open Power BI Desktop
2. Connect to their data source
3. File → Save As → select "Power BI Project (.pbip)" format
4. This creates the full boilerplate structure that this skill needs

Step 1: Gather Requirements

Ask the user:

1. Target PBIP project path — where to write the files (must already exist as a saved PBIP)
2. Page name and purpose — e.g., "Sales Overview", "Product Drillthrough"
3. Canvas size — read from existing page.json files or use default 1280x720
4. Visuals needed — what charts/cards/tables, and what data they show
5. Measures and columns — table.field references for each visual (case-sensitive, must match model exactly)
6. Layout — natural language ("4 KPIs at top, bar chart left, line chart right") or pixel positions

If the user has a background SVG from the Background Designer skill, use those exact grid positions.

Step 2: Generate the PBIR Files

Write files directly into the project's .Report/definition/ folder.

File Generation Order:

1. Create page folder: definition/pages/pg##Name/
2. Create page.json in that folder
3. Create visuals/ subfolder
4. For each visual, create visuals/v##Name/visual.json
5. Update definition/pages/pages.json — add the new page to pageOrder

Step 3: Naming Convention

ALWAYS use readable names:

• Pages: pg01Overview, pg02SalesDetail, pg03Drillthrough
• Visuals: v01KpiTotalSales, v02BarByRegion, v03LineTrend
• The name field inside the JSON MUST match the folder name exactly

See page-naming.md for full convention.

Step 4: Deliver

Tell the user:

1. Files have been written to [path]
2. Close Power BI Desktop if open, then reopen the .pbip file
3. The new page should appear with all visuals

JSON Structure Reference

page.json Template

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/page/2.0.0/schema.json",
  "name": "pg01Overview",
  "displayName": "Overview",
  "displayOption": "FitToPage",
  "width": 1280,
  "height": 720
}

Schema version detection: Before writing any files, read an existing visual.json from the project to discover the schema version Desktop used (e.g., 2.6.0, 2.7.0). Use that same version for all new files. The template above shows 2.0.0 as a baseline — always override with the detected version.

Canvas sizes:

• Standard: 1280 x 720
• Report: 1300 x 900
• Wide: 1600 x 900
• Full HD: 1920 x 1080

Page types:

• Standard: omit type field
• Drillthrough: add "type": "Drillthrough"
• Tooltip: add "type": "Tooltip", use smaller dimensions (320x240)
• Hidden: add "visibility": "HiddenInViewMode"

pages.json — Adding a New Page

Read existing pages.json, add the new page name to pageOrder:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/pagesMetadata/1.0.0/schema.json",
  "pageOrder": ["pg01Overview", "pg02NewPage"],
  "activePageName": "pg01Overview"
}

visual.json — Visual Container Structure

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.0.0/schema.json",
  "name": "v01KpiTotalSales",
  "position": {
    "x": 30,
    "y": 80,
    "z": 1000,
    "width": 280,
    "height": 150,
    "tabOrder": 0
  },
  "visual": {
    "visualType": "cardVisual",
    "query": {
      "queryState": {
        "ROLE_NAME": {
          "projections": [
            {
              "field": { "..." : "..." },
              "queryRef": "Table.Field",
              "nativeQueryRef": "Field"
            }
          ]
        }
      }
    },
    "objects": {},
    "drillFilterOtherVisuals": true
  }
}

Visual Type Patterns

KPI Card (cardVisual) — The Core Pattern

This is the most common visual. Shows a main value, a comparison reference, and a change percentage with conditional coloring.

Query roles:

• Data — main KPI value (e.g., Total Sales CY)
• ReferenceLabels — comparison value (e.g., Total Sales PY)
• AdditionalMeasure — change metric (e.g., YoY Sales %)

Conditional color via measure: The KPI Color measure returns a hex color based on YoY performance. Use the IBCS color palette consistently: "#44C088" (green/positive) or "#ED7373" (red/negative). Do NOT use "#00B050" / "#FF0000" — those clash with the IBCS visual standards used elsewhere in the report.