pbir-format

Author and validate Power BI Enhanced Report (PBIR) JSON metadata files.

6|3|Updated Jul 4, 2026
One-click install
npx skills add https://github.com/InsightfulAnalytics/PBI_Agentic_Dev --skill pbir-format-insightfulanalytics
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pbir-format
Source: https://github.com/InsightfulAnalytics/PBI_Agentic_Dev/tree/main/plugins/pbip/skills/pbir-format
Command: npx skills add https://github.com/InsightfulAnalytics/PBI_Agentic_Dev --skill pbir-format-insightfulanalytics

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Hand-editing Power BI Enhanced Report (PBIR) JSON files is brittle: schema-valid edits can still break rendering, corrupt reports, or silently do nothing. This Skill provides the format reference, validation rules, and failure patterns needed to safely read, create, and modify PBIR report metadata. ## Core Features & Use Cases - PBIR structure and schema guidance: Covers report.json, page.json, visual.json, themes, filters, bookmarks, extension measures, and definition.pbir connection modes (byPath vs byConnection). - Failure diagnosis: Documents symptoms of broken hand-authored PBIR, such as UTF-8 BOM corruption, empty visuals, Missing_References after publishing, and formatting changes that do nothing. - Legacy conversion script: Includes a Python script that converts monolithic legacy report.json into the PBIR directory structure with per-page and per-visual files. - Use Case: A developer needs to add a conditional formatting rule and a new slicer to a thin report connected to a remote semantic model. The Skill directs them to the correct visual.json and theme references, warns about the no-BOM rule, and explains how to validate the result. ## Quick Start Ask the agent to add a conditional formatting rule to the revenue column of the table visual in your PBIR report and validate the change.

Frequently Asked Questions about pbir-format

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a legacy Power BI report.json to PBIR format?▼

Use the included convert_legacy_to_pbir.py script, pointing it at the folder containing the legacy report.json and an output directory. It generates the PBIR definition folder with version.json, report.json, pages, and per-visual visual.json files. PBIX files must be unzipped first; PBIT templates are not supported.

Why did my PBIR formatting change do nothing in Power BI?▼

Formatting follows a cascade: defaults, theme wildcards, theme visualTypes, then bespoke visual.json. A missing {"id": "default"} selector or a property placed in the wrong object (objects vs visualContainerObjects) causes silent no-ops. Check the visual-container-formatting and selectors references.

Why does Power BI Desktop show 'Issues were found' after editing PBIR files?▼

The most common cause is a UTF-8 BOM written by tools like Windows PowerShell 5.1 Set-Content, which breaks Desktop file-open. Other causes include duplicate filter names, misplaced keys (schemas are additionalProperties: false), or a missing "Schema": "extension" on extension measures.

Does a clean pbir validate guarantee the report will render?▼

No. pbir validate is a schema and reference checker only. Valid JSON can still fail to render due to invalid field bindings, cropped visuals, model performance issues, or blank data. Verify rendering in Power BI Desktop or via the ExportTo REST API after publishing.

Can I edit PBIR files directly or should I use a tool?▼

Prefer the pbir CLI tool (installable via uv or pip on macOS and Windows) because it has safeguards against corrupting report files. Fall back to direct JSON editing only when pbir is unavailable, and always back up the report first.

What is the difference between byPath and byConnection in definition.pbir?▼

byPath references a local semantic model folder for thick PBIP reports, while byConnection uses a powerbi:// connection string for thin reports bound to a remote model. Both use schema 2.0.0 and determine how the report resolves its data source.