PBIR Format Reference

PBIR Format Reference

Skill that teaches Claude about the Power BI Enhanced Report (PBIR) JSON format to read and use it. Doesn't support legacy report.json or layout report metadata. To convert from legacy to PBIR format, users have to open and save their reports in Power BI Desktop.

Follow within reason the mental model when working with reports.

Hard rule: Treat PBIR JSON as an implementation detail. Read it when schema context is useful, but make every report, visual, page, bookmark, filter, mobile-layout, and theme change through pbir. Never hand-edit, text-replace, or script writes to report JSON. If pbir cannot express a requested mutation, stop and report the capability gap instead of inventing a raw-JSON fallback.

General, critical guidance

• Check examples: Check examples for a valid report
• Take a backup: Make a copy of the report before modifying it
• PBIX vs PBIP vs PBIR: Work on a local .Report folder in PBIR format. Use Power BI Desktop or pbir report convert for supported conversions; do not unzip, rezip, or patch PBIX internals. Do not work directly on PBIT files.
• Valid JSON vs. Rendering JSON: Valid JSON does not guarantee rendering. A visual might not render if the bound field is invalid (missing, wrong table, or misspelled) in the visual.json, if the visual elements are cropped by their container, if a model performance issue causes the dax query to time out, if a model data quality issue results in (Blank) or empty values, etc. Check whether a visual rendered using tools like the chrome or chrome devTools MCP server if the report was published to Power BI, but it's often faster to just ask the user to check in Power BI Desktop or the browser.
• Hierarchical formatting cascade: In Power BI reports, formatting is determined by the following order of operations: defaults --> Theme wildcards (*) --> Theme visualTypes --> bespoke visual.json configuration. Theme overwrites defaults, visualType overrides wildcards in themes, and visual.json overrides all theme formatting. Prefer putting as much of the formatting in the theme as possible over bespoke visual.json formatting because then changes only need to happen in one place
• PBIR files are strict JSON: No comments allowed
• DON'T MAKE ASSUMPTIONS: Check the Microsoft documentation and other reputable resources for context if needed, or ask the user.

Report Structure

Report.Report/
+-- .pbi/localSettings.json                # Local-only, gitignored
+-- .platform                              # Fabric Git integration
+-- definition.pbir                        # Semantic model connection (byPath or byConnection) can open this file in Power BI Desktop to open the report
+-- mobileState.json                       # PBIR-Legacy artifact only; current PBIR stores phone layout per-visual in mobile.json
+-- semanticModelDiagramLayout.json        # Model diagrams
+-- CustomVisuals/                         # Private custom visuals only
+-- definition/
|   +-- version.json                       # REQUIRED -- PBIR version
|   +-- report.json                        # REQUIRED -- report-level config, including theme, report filters, settings
|   +-- reportExtensions.json              # Extension measures and visual calculations (report- and visual-level DAX)
|   +-- pages/
|   |   +-- pages.json                     # Page order, active page