pbir-format

PBIR フォーマットリファレンス

Claude に Power BI 拡張レポート（PBIR）の JSON フォーマットを理解させ、読み取って活用するためのスキルです。従来の report.json や layout のレポートメタデータには対応していません。従来の形式から PBIR 形式に変換するには、Power BI Desktop でレポートを開いて保存する必要があります。

レポートを扱う際は、mental model に可能な範囲で従ってください。

厳守事項： PBIR JSON は実装の詳細として扱ってください。スキーマの情報が役立つ場合は読み取ってもかまいませんが、レポート、ビジュアル、ページ、ブックマーク、フィルター、モバイルレイアウト、テーマの変更はすべて pbir を通じて行ってください。レポートの JSON を手作業で編集したり、テキスト置換したり、スクリプトで書き換えたりしないでください。pbir で要求された変更を実現できない場合は、代替手段として生の JSON を使う方法を考案せず、作業を中止して機能上の制約を報告してください。

全般的な重要事項

• サンプルを確認する： 有効なレポートについてはサンプルを確認してください
• バックアップを取る： 変更を加える前に、レポートのコピーを作成してください
• PBIX、PBIP、PBIR： PBIR 形式のローカルな .Report フォルダーを使用してください。対応する形式変換には Power BI Desktop または pbir report convert を使用し、PBIX の内部ファイルを展開、再圧縮、パッチ適用しないでください。PBIT ファイルを直接扱わないでください。
• 有効な JSON と描画可能な JSON： JSON が有効でも、描画されるとは限りません。visual.json のバインドされたフィールドが無効（存在しない、テーブルが違う、またはスペルミスがある）な場合、ビジュアル要素がコンテナーによって切り取られている場合、モデルのパフォーマンスの問題で DAX クエリがタイムアウトする場合、モデルのデータ品質の問題で（空白）や空の値が返される場合など、ビジュアルが描画されないことがあります。レポートが Power BI に公開されている場合は、chrome や chrome devTools MCP サーバーなどのツールを使ってビジュアルが描画されているか確認してください。ただし、多くの場合、Power BI Desktop またはブラウザーでユーザーに確認してもらうほうが早いでしょう。
• 階層的な書式設定の適用順序： Power BI レポートでは、次の順序で書式設定が決まります。既定値 --> テーマのワイルドカード（*） --> テーマの visualTypes --> 個別の visual.json 設定。テーマは既定値を上書きし、visualType はテーマのワイルドカードを上書きし、visual.json はすべてのテーマ書式設定を上書きします。変更を一か所で済ませられるため、個別の visual.json に設定するより、できるだけ多くの書式設定をテーマに含めてください
• PBIR ファイルは厳密な JSON です： コメントは使用できません
• 思い込みで判断しないでください： 必要に応じて Microsoft のドキュメントやその他の信頼できる情報源を確認するか、ユーザーに尋ねてください。

レポートの構造

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
|   |   +-- [PageName]/                    # Power BI Desktop may generate names with spaces; recommend no spaces for human-authored names
|   |       +-- page.json                  # Page-level properties, including size, background, filters
|   |       +-- visuals/
|   |           +-- [VisualName]/
|   |               +-- visual.json        # Visual config, formatting, and field data bindings <-- most important and complex file for report dev and formatting
|   |               +-- mobile.json        # Mobile formatting of the visual (niche)
|   +-- bookmarks/                         # Bookmarks are a bad practice and should be avoided if possible!
|       +-- bookmarks.json                 # Bookmark order and groups
|       +-- [id].bookmark.json             # Individual bookmark state containing a snapshot of the report basically
+-- StaticResources/
    +-- RegisteredResources/               # Custom themes, images
        +-- [ThemeName].json               # Custom theme <-- second most important and complex file for formatting
    +-- SharedResources/BaseThemes/        # Microsoft base themes

ルール

レポートのレビューやフィードバックを行う際は、mental model に可能な範囲で従ってください。

レポートの変更

1. ユーザーの依頼を理解します。必要に応じて質問してビジネス上の背景を明確にします。ビジネスプロセス、ユーザー、モデルに焦点を当ててください
2. レポートを効率よく調べ、関連するページとビジュアルを特定します
3. 接続先のセマンティックモデルを確認します。シンレポート（byConnection）では、fab、pbir、または te CLI ツールを使ってモデルを調べます。byPath では、Power BI Desktop のローカルモデルに接続します。モデルを理解すると、利用できるフィールドと計算ロジックがわかります
4. 変更する適切なビジュアルとページを特定します。必要に応じてユーザーに確認してください
5. 正しい PBIR 構造とプロパティ値を使って変更を計画します

レポートの作成

1. pbir new を使ってレポートを生成する点を除き、変更時と同じ手順で進めます。レポートの JSON を手作業でスキャフォールドしないでください
2. definition.pbir が適切に設定されていることを確認します（byPath または byConnection）
3. theme.json ファイルを使用します。推奨：SQLBI/Data Goblins テーマ
4. pbir add filter でフィルターを追加します。フィルターペインのリファレンスを参照してください

追加の検証

レポート設計の詳細なガイダンス（レイアウト、間隔、視覚的な階層、色、アクセシビリティ）については、pbi-report-design スキルを参照してください。検証で適用される主なルールは次のとおりです。

• カスタムテーマを使用します。ユーザーから別途指定がない限り、独自の visual.json よりもテーマで書式を適用します
• ビジュアル同士を重ねず、ビジュアル間とページ端との間隔を均等に保ちます
• 各ページにタイトル（テキストボックスまたは背景画像）を配置します。テキストボックスは文字が表示される高さ（24-28 pt）を確保します
• 3-30-300 ルールに従います。上部に KPI／カード、中部に内訳、下部に詳細を配置します。1 ページあたりのスライサーは最大 2-3 個とし、それ以上の絞り込みにはフィルターペインを使用します
• SVG や大幅にカスタマイズした標準ビジュアルよりも、Deneb、Python、R のカスタムビジュアルを優先します。洗練さと技術的負債のバランスを取ってください
• モデルメジャーでは実現できない場合に限り、レポート拡張機能（薄いレポートメジャー、ビジュアル計算）を使用します
• テーマのセマンティックカラー（"bad"、"good"）を参照する拡張機能またはモデルメジャーに、条件付き書式を集約します
• 色は装飾ではなく、視線を誘導するために一貫して使用します。カテゴリーが 5 つを超える場合は円グラフを避けます
• ビジュアルを論理的な順序（通常はメジャーの降順）に並べます。特別な理由がない限り、グラフの軸はゼロから始めます
• フォントを統一します。アクセシビリティのために altText を設定します。ビジュアルには内容がわかる名前（a1b2c3d4 ではなく revenue_bar_chart）を付けます
• 冗長なビジュアルをなくします。カーディナリティの高いスライサーでは「適用」ボタンの使用を検討します
• デプロイ前の検証については、Data Goblins のレポートチェックリストを参照してください

よくあるタスクで読むべき資料

タスク	参照先
ビジュアルを追加または変更する	references/visual-json.md -- 式の構文、フィールド参照、クエリロール、位置、objects と visualContainerObjects の違い、セレクター
書式や色を変更する	references/visual-container-formatting.md（コンテナーの外観）＋ references/theme.md（テーマレベルの書式設定）。個別のビジュアル書式設定よりも、テーマの変更を優先してください
条件付き書式を追加する	references/schema-patterns/conditional-formatting.md ＋ references/measures.md（条件付き書式用の拡張メジャー）
フィルターを追加または設定する	references/filter-pane.md -- 7 種類のフィルター、既定値、フィルターの検出
テーマを扱う	references/theme.md -- 継承、ワイルドカード、ビジュアルタイプの上書き、フィルターペインのスタイル設定、jq を使った確認と変更
ビジュアルの書式設定をテーマに反映する	references/theme.md -- pbir theme push-visual で再利用可能な書式設定をプレビューして適用する
ページのレイアウトや背景を変更する	references/page.md -- 寸法、背景、壁紙、visualInteractions
ツールチップページを作成する	references/page.md -- ツールチップページの設定（タイプ、サイズ、表示設定）＋ビジュアルでの visualTooltip のオプトイン
ドリルスルーページを作成する	references/page.md -- ページの filterConfig 内のドリルスルーフィルター
レポートの設定を変更する	references/report.md -- themeCollection、resourcePackages、settings、outspacePane
拡張メジャーを追加する	references/measures.md -- reportExtensions.json の構造、DAX パターン、参照方法
注釈／メタデータを追加する	references/annotations.md -- デプロイスクリプト、ドキュメント、外部ツール向けに、レポート、ページ、ビジュアルにカスタムの名前と値のメタデータを追加する
画像や SVG を追加する	references/images.md -- RegisteredResources、テーマ内の base64、SVG メジャー
テキストボックスを追加または変更する	references/textbox.md -- 段落、textRuns、textStyle
ビジュアルを並べ替える	references/sort-visuals.md -- クエリ内の sortDefinition
ページ間でスライサーを同期する	references/visual-json.md -- syncGroup（groupName、fieldChanges、filterChanges）
ビジュアルの相互作用を編集する	references/visual-json.md ＋ references/page.md -- page.json 内の visualInteractions（NoFilter、Filter、Highlight）
テーブル／マトリックスの列幅を変更する	references/visual-json.md -- メタデータセレクターを使った columnWidth
ビジュアルをグループ化する	references/visual-json.md -- visualGroup、parentGroupName、groupMode
ビジュアルやフィールドを非表示にする	references/visual-json.md -- ルートレベルの isHidden、クエリ射影の制御
グラフ要素（ラベル、マーカー、線）を書式設定する	references/visual-json.md -- labels、markers、lineStyles、dataPoint
分析用の線（参照線、傾向線、エラー線、予測線）を追加する	references/visual-json.md -- y1AxisReferenceLine、trend、error、forecast
ブックマークを扱う	references/bookmarks.md -- ブックマークの状態、フィルターのスナップショット、ビジュアルの表示／非表示
モデルのフィールドを見つける	references/semantic-model/finding-fields.md -- pbir model、te、fab コマンド
別のモデルに再バインドする	references/semantic-model/report-rebinding.md -- byPath と byConnection の変換
スキーマのバージョンを理解する	references/schemas.md -- すべてのスキーマタイプと現在のバージョン
準拠性を検証または確認する	references/validation.md -- 準拠性の観点、pbir validate のカテゴリ、名前と必須フィールドのルール、監査と検出のコマンド
ビジュアルがどのように DAX クエリを生成するかを理解する	references/semantic-model/inferring-queries-from-visuals.md -- ビジュアルのメタデータから SUMMARIZECOLUMNS へのマッピング、データロール、IGNORE() のコンテキスト
DAX クエリパターンを作成または検証する	references/semantic-model/model-queries.md -- SUMMARIZECOLUMNS パターン、ROW()、クエリの実行方法
レポート全体でテーブル名またはフィールド名を変更する	references/how-to/fix-broken-field-references.md -- pbir fields replace／replace-table の一連のワークフロー
モデル変更後に壊れたフィールド参照を修正する	references/how-to/fix-broken-field-references.md -- 名前変更、移動、削除されたフィールドの診断と修復ワークフロー、スライサー値に関する注意点
レガシーの report.json を PBIR 形式に変換する	references/how-to/convert-legacy-to-pbir.md -- 形式の違い、段階的な変換方法、projections から queryState へのマッピング、検証
reportExtensions.json のスキーマを理解する	references/report-extensions.md -- ファイルスキーマの構造、エンティティ、ビジュアル計算。DAX の作成パターンについては references/measures.md を参照してください
動的（メジャー駆動型）代替テキストを設定する	references/visual-container-formatting.md -- visualContainerObjects.general 内での Measure 式としての altText
テキストボックスに動的なテキストランを追加する	references/textbox.md -- メジャーにバインドされた textRuns。Desktop でのラウンドトリップが必要です
ドリルダウンのクロスフィルター動作を理解する	references/visual-json.md -- drillFilterOtherVisuals と visualInteractions
カスタムビジュアルを登録する（AppSource、組織ストア、プライベート .pbiviz）	references/report.md -- publicCustomVisuals、organizationCustomVisuals、resourcePackages
スキーマのバージョン連動を理解する	references/schemas.md -- 親／埋め込みスキーマセット、レポート間でのフラグメントのコピー
モバイル（電話）レイアウトを設定する	references/pbir-structure.md -- ビジュアルごとの mobile.json、座標空間、Git の管理方法
PBIR プロジェクトの Git 管理	references/pbir-structure.md -- 追跡対象、無視対象、Desktop に任せるもの

definition.pbir

レポートはセマンティックモデルに接続する必要があります。接続方法は次の2つです。

• byPath -- ローカル PBIP 参照／厚型レポート：{"byPath": {"path": "../Model.SemanticModel"}}（スキーマ 2.0.0）
• byConnection -- リモート／薄型レポート：{"byConnection": {"connectionString": "Data Source=powerbi://..."}}（スキーマ 2.0.0）

関連スキル

• pbip -- PBIP プロジェクトの操作：名前変更の連鎖、プロジェクトのフォーク、レポート JSON のパターン
• tmdl -- TMDL ファイル形式の作成と編集

参考資料

ドキュメントの取得： 最新の Power BI 開発者向け／レポート形式のドキュメントを取得するには、https://learn.microsoft.com を検索し、該当するページを取得してください。ユーザーのリクエストに基づいて検索し、十分な情報を得てから作業を進められるよう、必要に応じて複数回検索してください。

例：

• examples/K201-MonthSlicer.Report/ -- 7種類のビジュアル（slicer、advancedSlicerVisual、kpi、lineChart、scatterChart、tableEx、textbox）、拡張メジャー、ブックマーク、条件付き書式を含む実際の PBIR レポート
• examples/visuals/ -- 54個の単独の visual.json の例。カタログは examples/visuals/__index.md を参照してください。default/（最小限、テーマのみ）と formatted/（独自の書式設定、条件付き書式、グラデーション、フィルター）に分かれています。

主要な参考資料：

• references/visual-json.md -- visual.json：式、フィールド参照、クエリロール、位置、objects と vCO の違い、セレクター、並べ替え、フィルター、ドリルダウンの伝播
• references/desktop-bridge.md -- pbir desktop の再読み込みとスクリーンショットによるキャンバス上での PBIR 編集の検証、プレビュー設定、開いている PBIP の場所
• references/pbir-structure.md -- PBIR のフォルダー構造、mobile.json の保存メカニズム、Git の運用
• references/schemas.md -- スキーマのバージョン、URL、埋め込みスキーマの連携
• references/validation.md -- 適合性の観点と検証方法（スキーマ、名前と ID、必須フィールド、フィールド、列挙値、ロール、レイアウト、テーマ、セマンティック）；pbir validate のカテゴリ、監査および検出コマンド
• references/enumerations.md -- 有効なプロパティの列挙値
• references/version-json.md -- version.json の形式（簡潔な説明）
• references/platform.md -- .platform ファイルの形式（簡潔な説明）
• references/bookmarks.md -- ブックマークの構造と状態スナップショット

書式設定と式：

• references/theme.md -- テーマのワイルドカード、継承、カラーシステム、フィルターペインのスタイル設定、 ビジュアルの種類ごとのオーバーライド、および対応する pbir theme コマンド
• references/schema-patterns/ -- 式、セレクター、条件付き書式、ビジュアル計算
• references/visual-container-formatting.md -- objects と visualContainerObjects の詳細；動的（メジャー駆動型）altText
• references/measures-vs-literals.md -- メジャー式とリテラル値の使い分け
• references/measures.md -- 拡張メジャーのパターン

ビジュアルとページの構成：

• references/textbox.md -- テキストボックスのビジュアル形式；動的（メジャーにバインドされた）テキストラン
• references/page.md -- ページの構成と背景
• references/report.md -- レポートレベルの設定；カスタムビジュアルの登録（AppSource、組織ストア、プライベート .pbiviz）
• references/wallpaper.md -- レポートの壁紙／キャンバスの背景
• references/filter-pane.md -- フィルターペインの書式設定
• references/sort-visuals.md -- ビジュアルの並べ替え設定
• references/images.md -- 静的画像、テーマ内の base64、SVG メジャー
• references/report-extensions.md -- reportExtensions.json の形式
• references/annotations.md -- レポート、ページ、ビジュアルのカスタムメタデータ

セマンティックモデルとの統合：

• references/semantic-model/ -- フィールド参照、モデル構造、レポートの再バインド、クエリの推論

ハウツーガイド：

• references/how-to/ -- 高度な条件付き書式、ビジュアル内の SVG、壊れたフィールド参照の修正、レガシー形式から PBIR への変換