powerbi-report-authoring

> **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering # Power BI Report Authoring Skill (PBIR/PBIP Format) This skill enables reading, editing, and creation of Power BI report definition files in the **PBIR (Power BI Report)** format used by **PBIP (Power BI Project)** files. ## Must/Prefer/Avoid ### MUST - Use this skill only for concrete PBIR/PBIP report-file mechanics such as pages, visuals, filters, slicers, navigation, bookmarks, themes, formatting, validation, Desktop reloads, and screenshots. - Validate PBIR with `powerbi-report-author validate` after each logical batch. - Use `powerbi-desktop` reload/screenshot workflows for rendered-output changes. - Use CLI capability lookup before writing visual roles, formatting objects, enum values, selectors, or expression encodings. ### PREFER - Start from an approved `Design Brief:` or `_brief/report-spec.md` for greenfield report builds. - Route visual-design uncertainty to `powerbi-report-design` before writing files. - For semantic model metadata or model-side changes, use a semantic-model authoring skill, Power BI Modeling MCP, or local TMDL files when available. ### AVOID - Do not guess PBIR JSON from memory when CLI metadata or reference files are available. - Do not use only this skill for open-ended design, report planning, or Fabric report item CRUD; pair it with `powerbi-report-design`, `powerbi-report-planning`, or `powerbi-report-management`. ## Quick Start Workflow 0. **Plan/design routing** → for greenfield builds, read `powerbi-report-planning` first; for theming, visual style, layout, redesigns, or critiques, read `powerbi-report-design`. Return here for PBIR mechanics. Before authoring, use the `Design Brief:` yaml block from `_brief/report-spec.md` (or an approved inline `Design Brief:` block in the conversation) as implementation context. 1. **Set up/update CLIs** → before first use, confirm `powerbi-report-author` and the global `powerbi-desktop` command are available; see [CLI Setup](#cli-setup). 2. **Understand the model** → use the Semantic Model MCP Server/skill if available, or read TMDL files directly for table/column/measure names 3. **Desktop context** → for live Desktop status, opening PBIP/PBIX files, reloads, screenshots, or visual verification, use the `powerbi-desktop` CLI from `@microsoft/powerbi-desktop-bridge-cli`; see [Edit → Validate → Reload → Screenshot Loop](#edit--validate--reload--screenshot-loop). 4. **Route by intent** → use [Topic Files and Examples](#topic-files-and-examples) to pick the relevant guide. 5. **Use CLI metadata** → use [Authoring Metadata & Validation CLI](#authoring-metadata--validation-cli) for exact visual roles, formatting objects, property names, enum values, and selector requirements; do not infer these from memory. 6. **Check common pitfalls** → read [Anti-Patterns and Pitfalls](#anti-patterns-and-pitfalls) before editing or validating when the change touches visuals, bindings, filters, formatting, layout, or Desktop rendering. 7. **Validate** → run `powerbi-report-author validate <path-to-.Report-dir>` after every logical batch of PBIR changes; see [Validation](#validation). 8. **Verify rendering** → for any rendered-output change, use `powerbi-desktop` reload + screenshots; see [Edit → Validate → Reload → Screenshot Loop](#edit--validate--reload--screenshot-loop) and [Screenshot Review](#screenshot-review). Do not proceed until both validation and visual review pass. For dashboard/report builds, page scaffolding is not completion — each requested page needs data-bound visuals. 9. **Report back** → give the user a concise summary of what was done and any issues encountered (major and minor). ## Topic Files and Examples Use the user's intent to choose the relevant topic file(s) before editing: | File | When to read | |------|-------------| | [`authoring.md`](references/authoring.md) | Adding/modifying pages, visuals, drillthrough, interactions — includes complete JSON examples | | [`powerbi-desktop.md`](references/powerbi-desktop.md) | Live Desktop verification — `powerbi-desktop` commands, PID selection, reload, screenshots, errors, troubleshooting | | [`screenshot-review.md`](references/screenshot-review.md) | Screenshot review checklist and rendered-output troubleshooting after Desktop screenshot capture | | [`formatting-overview.md`](references/formatting-overview.md) | **Read first for appearance changes** — cascade model, encoding rules, selectors, routing to other formatting files | | [`formatting.md`](references/formatting.md) | Editing `visual.json` appearance — selectors, VCOs, encoding mechanics, background-image routing, cascade | | [`color-strategy.md`](references/color-strategy.md) | Chart data point colors — theme `dataColors` vs `dataPoint.defaultColor` vs `dataPoint.fill` with selectors, cross-visual measure-color consistency | | [`conditional-formatting.md`](references/conditional-formatting.md) | Data-driven formatting — color gradients (FillRule), rules-based, icon sets, data bars, web URL, field value | | [`page-formatting.md`](references/page-formatting.md) | Editing `page.json` appearance — canvas background, wallpaper, page background images | | [`filter-pane.md`](references/filter-pane.md) | Filter pane (`outspacePane`) and filter card (`filterCard`) chrome — Applied/Available state styling, pane width, search/checkbox colors | | [`theming.md`](references/theming.md) | Creating or editing `theme.json` — dataColors, textClasses, visualStyles, style presets, ThemeDataColor reference | | [`re-theming.md`](references/re-theming.md) | **Switching themes on a report with existing visuals** — re-theming workflow (color mapping + bulk sweep), dark mode checklist, dark↔light polarity changes. Pair with `theming.md` when changing colors on a report with per-visual overrides. | | [`expressions.md`](references/expressions.md) | Building field references (Column, Measure, Aggregation, Hierarchy) and sort definitions | | [`filters.md`](references/filters.md) | Adding/modifying filters — includes complete JSON examples | | [`slicers.md`](references/slicers.md) | **Read first** when adding/modifying slicers or slicer selections — agent workflow, JSON templates, selection config | | [`cartesian.md`](references/cartesian.md) | Adding bar, column, line charts — families, roles, query patterns (multi-measure, drill hierarchy, date hierarchy), formatting | | [`map.md`](references/map.md) | Adding map visuals — template, roles, geocoding workflow, handling render failures | | [`card.md`](references/card.md) | Adding or formatting KPI/card visuals — `cardVisual`, id selectors, callout/value sizing, accent bars | | [`table.md`](references/table.md) | Adding or formatting tables/matrices — `tableEx`, `pivotTable`, grow-to-fit columns, row banding | | [`image.md`](references/image.md) | Adding image visuals — local resources, URLs, data-bound images, OneLake file URLs, ImageUrl validation/refusal workflow; also plot area background images for chart visuals | | [`shape.md`](references/shape.md) | Adding shape visuals — containers, dividers, backgrounds, reference-image matching | | [`textbox.md`](references/textbox.md) | Adding static or dynamic textbox visuals — paragraphs, text runs, and bound value expressions | | [`version-control.md`](references/version-control.md) | Git branching, committing, reverting — read when the task involves version control or safe rollback planning | ### Greenfield / Design Handoff > This skill owns PBIR file mechanics once the work is concrete: page/visual > JSON, bindings, filters, slicers, themes, formatting, navigation, bookmarks, > validation, Desktop reloads, and screenshots. > > Use `powerbi-report-planning` before authoring for new report/dashboard > requests, requirements gathering, dependency checks, approval, or end-to-end > build sequencing. Use `powerbi-report-design` for open-ended visual design, > redesign/restyle, brand/theme direction, chart selection, or layout critique. > Return here once there is an approved spec/design brief or a concrete PBIR > edit to implement — see Quick Start step 0 for how to consume the brief. ### Large Build Execution For full report/PBIP builds, do **not** delegate complete PBIP generation to a subagent — the owning agent must keep the design brief, model inventory, cross-page consistency, validation loop, and Desktop verification coordinated. When context or repetition is the constraint, prefer a deterministic Node.js generator that reads the approved design brief and writes PBIR JSON. If delegation is still useful, split it by page or visual family and give each subagent the relevant brief excerpt, exact fields/measures, and layout/visual contract; have it return scoped PBIR JSON or a patch for the owning agent to integrate and validate. ## CLI Setup **Prerequisite: Node.js 20 or later.** Check with `node --version`. If missing or older, install from [nodejs.org](https://nodejs.org/) or via your package manager — Windows: `winget install OpenJS.NodeJS.LTS`; macOS: `brew install node`; Linux: distro package or [nodesource](https://github.com/nodesource/distributions). Before using the CLIs in a session, ensure the latest global versions are installed: ```bash npm install -g @microsoft/powerbi-report-authoring-cli@latest @microsoft/powerbi-desktop-bridge-cli@latest ``` Confirm both are on `PATH`: ```bash powerbi-report-author --version powerbi-desktop --version ``` ## PBIR File Layout A PBIP project on disk looks like this: ```text <Report>.pbip # Project manifest ├── <Report>.Report/ │ ├── .platform # Fabric metadata (type, logicalId) │ ├── definition.pbir # Report → SemanticModel binding │ ├── definition/ │ │ ├── version.json # Format version (e.g. "2.0.0") │ │ ├── report.json # Report-level: themes, settings, resources │ │ └── pages/ │ │ ├── pages.json # Page order + active page name │ │ └── <pageId>/ │ │ ├── page.json # Page: displayName, size, type, filters │ │ └── visuals/ │ │ └── <visualId>/ │ │ └── visual.json # Visual: type, position, query, formatting │ ├── CustomVisuals/ # Third-party .pbiviz packages │ └── StaticResources/ │ ├── SharedResources/BaseThemes/ # Built-in base themes │ └── RegisteredResources/ # User images, custom theme JSON └── <Report>.SemanticModel/ # OUT OF SCOPE ``` ### Key Files | File | Purpose | Agent rule | |------|---------|------------| | `.platform` | Fabric/PBIP report item metadata | Keep it with the `.Report` folder | | `definition.pbir` | Report → semantic model binding via `byPath` or `byConnection` | Preserve schema/version unless intentionally migrating | | `version.json` | PBIR format metadata | Preserve the full scaffolded file, including `$schema` | | `report.json` | Report-level settings, themes, resources | Edit through references and validate after changes | | `pages.json` | Page order and active page | Add every new page to `pageOrder`; preserve `activePageName` | | `page.json` | Page metadata, size, filters | Preserve dimensions unless resizing is approved | | `visual.json` | Visual type, position, query, formatting | Validate roles and formatting with CLI metadata | | `localSettings.json` | User-local settings | Do not commit or rely on it | Schema URLs use the prefix `developer.microsoft.com/json-schemas/fabric/item/report/definition/`. The suffixes are versioned PBIR contracts that Power BI Desktop bumps with most releases (e.g. `visualContainer/2.9.0`, `page/2.1.0`, `report/3.3.0` at the time of writing — newer values may appear in any user's PBIP). When editing, **always preserve the existing `$schema` value**; when adding a new file, copy the `$schema` URL from an existing file of the same type in the same report. Do not invent or bump versions on your own. Validate with `powerbi-report-author validate`. --- ## Authoring Metadata & Validation CLI Use `powerbi-report-author` whenever you need PBIR facts that should not be guessed: visual types, data roles, formatting objects, property names, enum values, selectors, expression/value encodings, and report validation. The CLI is the source of truth for PBIR authoring details; examples and memory are not. | Command | Purpose | When to use | |---------|---------|-------------| | `catalog list` | List all built-in visual types (and any deprecated entries) | Choosing a visual type | | `catalog describe <type>` | Roles, formatting keys, cardinality | Before creating/editing a visual | | `formatting list-objects <type>` | Valid `objects.*` keys + VCO keys; flags objects needing id selectors | Before applying formatting | | `formatting describe-object <type> <object>` | Property names, types, enum values, descriptions; `_selectorHint` when id selector required | Finding exact property names and allowed values | | `formatting describe-property <type> <object> <prop>` | Focused single-property lookup | When you already know the object and want just one property | | `formatting search <type> <regex>` | Regex search across all formatting objects + VCOs | **When you don't know which object a property belongs to** | | `formatting list-vcos` | Enumerate shared visualContainerObjects | Auditing chrome/container formatting surface | | `validate <path>` | Full validation of a `.pbip` or `.Report` directory: JSON Schema, structure, IDs, formatting properties, enum values, nesting, layout bounds, theme | **After every batch of changes** | | `preview-* <path> [--with-derived]` | Report inventory: `preview-visuals`, `preview-pages`, `preview-filters`, `preview-themes` | Auditing existing report content | | `--help` / `<command> --help` | Command syntax and available options | Before using an unfamiliar command or flag | More commands: [`powerbi-report-author-cli.md`](references/powerbi-report-author-cli.md). ### Validation result handling Run `powerbi-report-author validate <path-to-.Report-dir>` after every logical batch of PBIR edits. - `failed` / non-zero exit: fix every error before Desktop reload. Desktop may reject or misrender invalid PBIR. - `succeededWithWarnings`: review warnings before proceeding. Unknown visual types or theme visual keys usually mean a typo unless the report intentionally uses a custom `.pbiviz`. - Diagnostics include file paths and JSON paths. Use them to jump directly to the broken node. - For large diagnostics, use `--pretty` for readable output or `--out <file>` to write the full result to a file. ## Visual Capability Guardrails Use these as pre-edit safety rails. Always confirm exact roles, formatting objects, properties, enum values, and selectors with `powerbi-report-author` before editing. ### Prefer modern visual types Never create legacy visual types. If repairing an existing legacy visual, migrate to the modern type and rebuild roles/formatting from CLI metadata. | Do not create | Use instead | |---|---| | `card` | `cardVisual` | | `multiRowCard` | `cardVisual` — use multi-value `cardVisual` (multiple projections in `Data`) for multiple KPIs | | `table` | `tableEx` | | `matrix` | `pivotTable` | | `map`, `filledMap` | `azureMap` | ### Instance Selectors Some formatting objects need `{ id: ... }` selectors. Run `formatting list-objects` and `formatting describe-object`; follow `_selectorHint` and the dual-entry pattern in `references/formatting.md`. ## Edit → Validate → Reload → Screenshot Loop For rendered-output changes, follow this loop. Do not report completion until validation, reload, and screenshot review are clean. ```text ┌──────────────────────────────────────────────────────────┐ │ 1. Edit PBIR files │ │ 2. Validate → errors? fix and go to 1 │ │ 3. Desktop status → choose the correct bridge PID │ │ 4. Desktop reload → error? fix PBIR and go to 1 │ │ 5. Screenshot/review → issues? fix and go to 1 │ │ 6. Clean → report completion │ └──────────────────────────────────────────────────────────┘ ``` **Rules:** - **Step 2** — `powerbi-report-author validate <path-to-.Report-dir>`. Pass the report definition directory (e.g., `Sales.Report`), not the `.pbip` file or project root. Fix all errors before reload — invalid PBIR errors will surface in Desktop. - **Steps 3–5** — use `powerbi-desktop` CLI: `status` to choose the PID, then `reload --pid <pid>` for PBIP/PBIR current files and screenshots from the same PID. Then perform the screenshot review below. After `status`, if the selected instance has `hasUnsavedChanges: true`, do not reload yet; ask the user to save or discard their Desktop UI changes,