powerbi-report-authoring

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を確認するには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用してください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を確認するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath フィルタリングを使用してください。

Power BI レポート作成スキル（PBIR/PBIP 形式）

このスキルを使用すると、PBIP（Power BI Project） ファイルで使用される PBIR（Power BI Report） 形式の Power BI レポート定義ファイルを読み取り、編集、作成できます。

必須／推奨／回避

必須

• このスキルは、ページ、ビジュアル、フィルター、スライサー、ナビゲーション、ブックマーク、テーマ、書式設定、検証、Desktop の再読み込み、スクリーンショットなど、具体的な PBIR/PBIP レポートファイルの操作にのみ使用してください。
• 論理的なまとまりごとに変更を加えた後、powerbi-report-author validate で PBIR を検証してください。
• レンダリング結果に影響する変更には、powerbi-desktop の再読み込み／スクリーンショットのワークフローを使用してください。
• ビジュアルのロール、書式設定オブジェクト、列挙値、セレクター、式のエンコーディングを記述する前に、CLI の機能を確認してください。

推奨

• 新規レポートを作成する場合は、承認済みの Design Brief: または _brief/report-spec.md を出発点にしてください。
• ビジュアルデザインに不確実な点がある場合は、ファイルを記述する前に powerbi-report-design を利用してください。
• セマンティックモデルのメタデータやモデル側の変更には、利用可能な場合、セマンティックモデル作成スキル、Power BI Modeling MCP、またはローカルの TMDL ファイルを使用してください。

回避

• CLI のメタデータやリファレンスファイルが利用できる場合、記憶だけを頼りに PBIR JSON を推測しないでください。
• 自由形式のデザイン、レポートの計画、Fabric レポートアイテムの CRUD にこのスキルだけを使用しないでください。powerbi-report-design、powerbi-report-planning、または powerbi-report-management と併用してください。

クイックスタートのワークフロー

0. 計画とデザインの振り分け → 新規構築の場合は、まず powerbi-report-planning を読みます。テーマ設定、ビジュアルスタイル、レイアウト、再デザイン、またはレビューの場合は、powerbi-report-design を読みます。PBIR の仕組みについては、ここに戻ってください。作成を始める前に、_brief/report-spec.md の Design Brief: YAML ブロック（または会話内で承認されたインラインの Design Brief: ブロック）を実装のコンテキストとして使用してください。
1. CLI のセットアップ／更新 → 初回使用の前に、powerbi-report-author とグローバルの powerbi-desktop コマンドが利用可能であることを確認してください。CLI のセットアップを参照してください。
2. モデルの理解 → 利用可能な場合は Semantic Model MCP Server／スキルを使用するか、テーブル名、列名、メジャー名を確認するために TMDL ファイルを直接読んでください。
3. Desktop のコンテキスト → Desktop の現在の状態、PBIP／PBIX ファイルの開閉、再読み込み、スクリーンショット、またはビジュアルの確認には、@microsoft/powerbi-desktop-bridge-cli の powerbi-desktop CLI を使用してください。編集 → 検証 → 再読み込み → スクリーンショットのループを参照してください。
4. 目的に応じた振り分け → 該当するガイドを選ぶには、トピックファイルと例を使用してください。
5. CLI メタデータの使用 → ビジュアルロール、書式設定オブジェクト、プロパティ名、列挙値、セレクター要件を正確に確認するには、作成メタデータと検証 CLIを使用してください。記憶を頼りに推測しないでください。
6. よくある落とし穴の確認 → 変更がビジュアル、バインディング、フィルター、書式設定、レイアウト、または Desktop のレンダリングに関わる場合は、編集または検証の前にアンチパターンと落とし穴を読んでください。
7. 検証 → PBIR の変更を論理的な単位で行うたびに、powerbi-report-author validate <path-to-.Report-dir> を実行してください。検証を参照してください。
8. レンダリングの確認 → レンダリング結果が変わる場合は、powerbi-desktop で再読み込みし、スクリーンショットを撮影してください。編集 → 検証 → 再読み込み → スクリーンショットのループとスクリーンショットのレビューを参照してください。検証とビジュアルレビューの両方に合格するまで、先に進まないでください。ダッシュボード／レポートの構築では、ページの骨組みを用意しただけでは完了ではありません。依頼された各ページに、データにバインドされたビジュアルが必要です。
9. 結果の報告 → 実施内容と発生した問題（重大なものと軽微なもの）を、簡潔にユーザーへ報告してください。

トピックファイルと例

編集を始める前に、ユーザーの意図に基づいて関連するトピックファイルを選んでください。

ファイル	読むタイミング
authoring.md	ページ、ビジュアル、ドリルスルー、インタラクションの追加・変更 — 完全な JSON の例を含みます
powerbi-desktop.md	Desktop でのライブ検証 — powerbi-desktop コマンド、PID の選択、再読み込み、スクリーンショット、エラー、トラブルシューティング
screenshot-review.md	Desktop でスクリーンショットを撮影した後の、スクリーンショット確認チェックリストとレンダリング結果のトラブルシューティング
formatting-overview.md	外観の変更時は最初に読んでください — カスケードモデル、エンコード規則、セレクター、他の書式設定ファイルへの案内
formatting.md	visual.json の外観の編集 — セレクター、VCO、エンコードの仕組み、背景画像の案内、カスケード
color-strategy.md	グラフのデータポイントの色 — テーマの dataColors と dataPoint.defaultColor、セレクターを使った dataPoint.fill、ビジュアル間でのメジャーの色の一貫性
conditional-formatting.md	データに基づく書式設定 — 色のグラデーション（FillRule）、ルールベース、アイコンセット、データバー、Web URL、フィールド値
page-formatting.md	page.json の外観の編集 — キャンバスの背景、壁紙、ページの背景画像
filter-pane.md	フィルターペイン（outspacePane）とフィルターカード（filterCard）の外観 — 適用済み／利用可能状態のスタイル設定、ペインの幅、検索／チェックボックスの色
theming.md	theme.json の作成・編集 — dataColors、textClasses、visualStyles、スタイルプリセット、ThemeDataColor リファレンス
re-theming.md	既存のビジュアルがあるレポートのテーマを切り替える場合 — テーマ変更のワークフロー（色のマッピングと一括適用）、ダークモードのチェックリスト、ダーク／ライト間の明暗反転。ビジュアルごとの上書きがあるレポートの色を変更する場合は、theming.md と併せて使用してください。
expressions.md	フィールド参照（Column、Measure、Aggregation、Hierarchy）と並べ替え定義の作成
filters.md	フィルターの追加・変更 — 完全な JSON の例を含みます
slicers.md	スライサーやスライサーの選択状態を追加・変更する場合は最初に読んでください — エージェントのワークフロー、JSON テンプレート、選択設定
cartesian.md	棒グラフ、縦棒グラフ、折れ線グラフの追加 — ファミリー、ロール、クエリパターン（複数メジャー、ドリル階層、日付階層）、書式設定
map.md	マップビジュアルの追加 — テンプレート、ロール、ジオコーディングのワークフロー、レンダリング失敗への対処
card.md	KPI／カードビジュアルの追加・書式設定 — cardVisual、ID セレクター、コールアウト／値のサイズ調整、アクセントバー
table.md	テーブル／マトリックスの追加・書式設定 — tableEx、pivotTable、列幅の自動調整、行の縞模様
image.md	画像ビジュアルの追加 — ローカルリソース、URL、データバインド画像、ImageUrl の検証／拒否ワークフロー。また、グラフビジュアルのプロット領域の背景画像も扱います
shape.md	図形ビジュアルの追加 — コンテナー、区切り線、背景、参照画像との照合
textbox.md	静的または動的なテキストボックスビジュアルの追加 — 段落、テキストラン、バインドされた値の式
version-control.md	Git のブランチ作成、コミット、取り消し — バージョン管理または安全なロールバック計画が関わるタスクでは読んでください

Greenfield / Design Handoff

作業内容が具体化した後の PBIR ファイルの仕組みは、このスキルが担当します。ページ／ビジュアルの JSON、バインディング、フィルター、スライサー、テーマ、書式設定、ナビゲーション、ブックマーク、検証、Desktop での再読み込み、スクリーンショットが対象です。

新しいレポート／ダッシュボードの依頼、要件の収集、依存関係の確認、承認、エンドツーエンドの構築手順の策定を行う場合は、作成前に powerbi-report-planning を使用してください。自由度の高いビジュアルデザイン、再デザイン／スタイル変更、ブランド／テーマの方向性、グラフの選定、レイアウトの評価には powerbi-report-design を使用してください。承認済みの仕様／デザイン概要がある場合、または実装する具体的な PBIR の編集内容がある場合は、ここに戻ってください。概要の利用方法については、Quick Start のステップ 0 を参照してください。

大規模な構築の実行

レポート／PBIP 全体を構築する場合、PBIP の生成全体をサブエージェントに委任しないでください。担当エージェントは、デザイン概要、モデルのインベントリ、ページ間の一貫性、検証サイクル、Desktop での確認を連携して進める必要があります。

コンテキストや反復作業が制約となる場合は、承認済みのデザイン概要を読み取り、PBIR JSON を書き出す決定論的な Node.js ジェネレーターを優先してください。それでも委任が有用であれば、ページまたはビジュアルの種類ごとに分割し、各サブエージェントに関連する概要の抜粋、正確なフィールド／メジャー、レイアウト／ビジュアルの仕様を渡してください。担当エージェントが統合して検証できるよう、範囲を限定した PBIR JSON またはパッチを返すよう指示してください。

CLI のセットアップ

前提条件：Node.js 20 以降。 node --version で確認してください。インストールされていない場合、またはバージョンが古い場合は、nodejs.org またはパッケージマネージャーからインストールしてください。Windows：winget install OpenJS.NodeJS.LTS、macOS：brew install node、Linux：ディストリビューションのパッケージまたは nodesource を利用してください。

セッションで CLI を使用する前に、最新のグローバルバージョンがインストールされていることを確認してください。

npm install -g @microsoft/powerbi-report-authoring-cli@latest @microsoft/powerbi-desktop-bridge-cli@latest

両方が PATH に含まれていることを確認してください。

powerbi-report-author --version
powerbi-desktop --version

PBIR ファイルのレイアウト

ディスク上の PBIP プロジェクトは、次のような構成です。

<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

主なファイル

ファイル	用途	エージェントのルール
.platform	Fabric／PBIP レポート項目のメタデータ	.Report フォルダーと一緒に保持してください
definition.pbir	byPath または byConnection によるレポートからセマンティックモデルへのバインディング	意図的に移行する場合を除き、スキーマ／バージョンを保持してください
version.json	PBIR 形式のメタデータ	$schema を含め、足場として生成されたファイル全体を保持してください
report.json	レポートレベルの設定、テーマ、リソース	参照を通じて編集し、変更後に検証してください
pages.json	ページの順序とアクティブなページ	新しいページはすべて pageOrder に追加し、activePageName を保持してください
page.json	ページのメタデータ、サイズ、フィルター	サイズ変更の承認がない限り、寸法を保持してください
visual.json	ビジュアルの種類、位置、クエリ、書式設定	CLI のメタデータを使ってロールと書式設定を検証してください
localSettings.json	ユーザーのローカル設定	コミットしたり、依存したりしないでください

スキーマ URL のプレフィックスは developer.microsoft.com/json-schemas/fabric/item/report/definition/ です。 サフィックスはバージョン管理された PBIR の仕様で、Power BI Desktop の多くのリリースに伴って更新されます（執筆時点では visualContainer/2.9.0、page/2.1.0、report/3.3.0 などです。ユーザーの PBIP に、これより新しい値が含まれている場合があります）。編集時は、既存の $schema の値を必ず保持してください。新しいファイルを追加する場合は、同じレポート内にある同じ種類の既存ファイルから $schema URL をコピーしてください。独自にバージョンを推測したり、更新したりしないでください。powerbi-report-author validate で検証してください。

---

作成メタデータと検証 CLI

推測で補うべきでない PBIR の情報（ビジュアルの種類、データロール、書式設定オブジェクト、プロパティ名、列挙値、セレクター、式／値のエンコーディング、レポートの検証）が必要な場合は、powerbi-report-author を使用してください。PBIR の作成に関する詳細の信頼できる情報源は CLI です。サンプルや記憶ではありません。

コマンド	目的	使用するタイミング
catalog list	組み込みのビジュアルの種類（非推奨の項目を含む）をすべて一覧表示する	ビジュアルの種類を選ぶとき
catalog describe <type>	ロール、書式設定キー、基数	ビジュアルの作成／編集前
formatting list-objects <type>	有効な objects.* キーと VCO キーを一覧表示する。id セレクターが必要なオブジェクトにはフラグを付ける	書式設定を適用する前
formatting describe-object <type> <object>	プロパティ名、型、列挙値、説明。id セレクターが必要な場合は _selectorHint も表示する	正確なプロパティ名と使用可能な値を調べるとき
formatting describe-property <type> <object> <prop>	単一のプロパティに絞った検索	オブジェクトが分かっていて、プロパティだけを調べたいとき
formatting search <type> <regex>	すべての書式設定オブジェクトと VCO を対象に正規表現で検索する	プロパティがどのオブジェクトに属するか分からないとき
formatting list-vcos	共通の visualContainerObjects を列挙する	クローム／コンテナーの書式設定範囲を監査するとき
validate <path>	.pbip または .Report ディレクトリを完全に検証する：JSON Schema、構造、ID、書式設定プロパティ、列挙値、ネスト、レイアウト境界、テーマ	変更をまとめて適用した後
preview-* <path> [--with-derived]	レポートの内容一覧：preview-visuals、preview-pages、preview-filters、preview-themes	既存のレポート内容を監査するとき
--help / <command> --help	コマンドの構文と使用可能なオプション	初めて使うコマンドやフラグを実行する前

その他のコマンド： powerbi-report-author-cli.md 。

検証結果の処理

PBIR の編集を論理的なまとまりごとに適用した後は、powerbi-report-author validate <path-to-.Report-dir> を実行してください。

• failed／ゼロ以外の終了コード：Desktop で再読み込みする前に、すべてのエラーを修正してください。無効な PBIR は Desktop で拒否されたり、正しく描画されなかったりすることがあります。
• succeededWithWarnings：続行する前に警告を確認してください。不明なビジュアルの種類やテーマのビジュアルキーは、レポートが意図的にカスタム .pbiviz を使用している場合を除き、通常はタイプミスを示しています。
• 診断情報にはファイルパスと JSON パスが含まれます。問題のあるノードに直接移動するために使用してください。
• 診断情報が大量にある場合は、--pretty で読みやすく表示するか、--out <file> で結果全体をファイルに書き出してください。

ビジュアル機能のガードレール

編集前の安全策として、以下を使用してください。編集前に必ず powerbi-report-author で、正確なロール、書式設定オブジェクト、プロパティ、列挙値、セレクターを確認してください。

モダンなビジュアルの種類を優先する

レガシーなビジュアルの種類は新規作成しないでください。既存のレガシービジュアルを修正する場合は、モダンな種類に移行し、CLI のメタデータを参照してロールと書式設定を再構築してください。

作成しないもの	代わりに使用
card	cardVisual
multiRowCard	cardVisual — 複数の KPI には、複数の投影を Data に含めるマルチバリューの cardVisual を使用します
table	tableEx
matrix	pivotTable
map、filledMap	azureMap

インスタンスセレクター

書式設定オブジェクトによっては、{ id: ... } セレクターが必要です。formatting list-objects と formatting describe-object を実行し、_selectorHint と references/formatting.md の二重エントリーパターンに従ってください。

編集 → 検証 → 再読み込み → スクリーンショットのループ

描画結果に影響する変更では、このループに従ってください。検証、再読み込み、スクリーンショットの確認がすべて問題なく完了するまで、作業の完了を報告しないでください。

┌──────────────────────────────────────────────────────────┐
│  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               │
└──────────────────────────────────────────────────────────┘

ルール：

• ステップ 2 — powerbi-report-author validate <path-to-.Report-dir> を実行します。.pbip ファイルやプロジェクトのルートではなく、レポート定義ディレクトリ（例：Sales.Report）を渡します。再読み込みの前に、すべてのエラーを修正してください。無効な PBIR エラーは Desktop に表示されます。
• ステップ 3～5 — powerbi-desktop CLI を使用します。status で PID を選択し、reload --pid <pid> を実行して、同じ PID から PBIP/PBIR の最新ファイルとスクリーンショットを取得します。その後、以下のスクリーンショットレビューを実施します。 status の実行後、選択したインスタンスの hasUnsavedChanges: true が示されている場合は、まだ再読み込みしないでください。Desktop UI の変更を保存するか破棄するようユーザーに依頼し、status を再実行して、値が false になってから続行します。 reload が対象とするのはレポート/PBIR の変更のみです。セマンティックモデル/TMDL の変更には、セマンティックモデルのスキルまたは Modeling MCP を使用し、変更が反映されていない場合は PBIP を開き直します。 例外： テーマ JSON ファイルは名前でキャッシュキーが設定されているため、Desktop で再読み込みしても編集内容が反映されないことがあります。テーマファイルの名前にランダムなサフィックスを付けて（report.json も更新します）、または Desktop を閉じて開き直してください。

Desktop CLI コマンド：

コマンド	用途	使用する場面
open "<path.pbip>"	PBIP/PBIX 用に Power BI Desktop を起動します	Desktop の起動時、または対象レポートを開くとき
status	Desktop Bridge のインスタンス、現在のファイル、レポートディレクトリ、ブリッジの状態を一覧表示します	再読み込み/スクリーンショットの前に実行し、正しい PID を選択するとき
reload --pid <pid>	選択した Desktop インスタンスで、現在の PBIP レポートファイルを再読み込みします	開いている PBIP で、検証済みの PBIR を編集した後
screenshot <page-id> --pid <pid> --output <file>	PBIR ページ ID を指定して、1 ページをキャプチャします	特定のページを変更したとき
screenshot-all --pid <pid> --output-dir <dir>	すべてのレポートページをキャプチャします	テーマ、ナビゲーション、ページ順、またはレポート全体を変更したとき

レビューが必要な PBIR ページが 1 つだけの場合は、powerbi-desktop screenshot <page-id> --pid <pid> を使用します。reload は PBIP に基づくレポートでのみサポートされています。powerbi-desktop のコマンドで --report を受け付けるものはありません。同じ PBIP が複数のプロセスで開かれている場合があるため、status を使用して PID で Desktop インスタンスを選択してください。スクリーンショットの既定のスケールは 2 です。同じ PID に対する再読み込みとスクリーンショットの操作は、常に直列で実行してください。低速または再試行可能なエラーへの対処であっても、同じ PID に対して並列で実行しないでください。すべてのコマンドリファレンスとトラブルシューティングのワークフローについては、references/powerbi-desktop.md を参照してください。

Desktop CLI の一般的な実行結果：

出力/エラー	意味	対処
"status": "not_connected"	検出可能な Desktop Bridge がない	powerbi-desktop open "<path.pbip>" を実行するか、ユーザーに Desktop の起動を依頼してください。それでも到達できない場合は、Desktop のプレビュー機能を有効にするよう依頼してください — ドキュメント を参照
AMBIGUOUS_DESKTOP_INSTANCE	複数の Desktop Bridge インスタンスが利用可能	powerbi-desktop status を実行し、目的の PID を選択して、--pid を付けて再試行してください
METHOD_NOT_AVAILABLE	Desktop ビルドに必要な本番ブリッジメソッドが欠けている	ユーザーに Desktop が古い/サポート対象外であることを伝えてください — ドキュメント を参照
HostNotReady / 再試行可能なブリッジエラー	Desktop は起動しているが、レポートホストの準備ができていない (リロード直後に起こることが多い)	CLI が自動的に再試行します。表面化した場合はもう一度実行してください。独自のスリープを追加しないでください — CLI の再試行パスに任せてください。
Timeout (ブリッジエラー)	リロードまたはスクリーンショットが CLI の再試行予算を超えた	status が bridgeStatus: "connected" を示していることを確認し、もう一度実行してください。Timeout が続く場合は、予算を引き上げてください (例: reload --pid <pid> --wait-seconds 120)。bridgeStatus: "error" の場合、または status がハングする場合は、Desktop のモーダルダイアログが入力をブロックしていないかユーザーに確認してください。
スクリーンショット/リロード中の Cancelled	リロード/スクリーンショットがキャンセルされた — 通常は同じ PID 上での同時リロード/スクリーンショットが原因です。Timeout (操作の実行時間が長すぎた) とは異なります。	PID ごとにリロードとスクリーンショットを直列に実行してください。status で connected になるのを待ち、1 つずつ再試行してください。
ReportDefinitionValidationFailed	Desktop が PBIR 定義を拒否した	PBIR を修正し、powerbi-report-author validate <path> を実行してから、再度リロードしてください
REPORT_DIR_REQUIRED	選択した PID に PBIP/PBIR の現在のファイルがない。reload/screenshot-all には PBIP/PBIR の状態が必要	status から正しい PID を選択するか、対象の PBIP を開いてください

スクリーンショットレビュー

スクリーンショットを撮影した後、完了を報告する前に、レンダリング出力の独立したレビューを実施してください。screenshot-review.md を読み、レイアウト、データのレンダリング、書式設定/テーマ、スライサー、および一般的なスクリーンショットの失敗モードを確認し、PBIR を修正してクリーンになるまでループを繰り返してください。

---

検証

PBIR 変更の論理的なバッチごとに powerbi-report-author validate <path> を実行してください。.Report ディレクトリを推奨しますが、CLI は .pbip ファイルや、単一の .Report ディレクトリを含むプロジェクトルートも受け付けます。エラーは Desktop のリロードをブロックするため、まずそれらを修正してください。警告を確認し、修正しない明確な理由がない限り修正してください。

バリデーターは、PBIR 構造、JSON/スキーマの妥当性、ファイル間参照、ID/名前、ビジュアルタイプ、ロールバインディング、フィルター、書式設定オブジェクト/プロパティ/列挙型/セレクター、visualContainerObjects、テーマ登録、レイアウト境界、および選択された Desktop/レンダリングの失敗パターンを網羅するオフラインのプリフライトです。これは Desktop のリロードとスクリーンショットレビューを置き換えるものではありません。

---

アンチパターンと落とし穴

落とし穴	結果	修正方法
フィルターの Where 条件内で "Entity" を使う	フィルターが警告なしに機能しない	From のエイリアスを使って "Source" を指定します
nativeQueryRef を省略する	ビジュアル計算が機能しなくなる場合があります	必ず nativeQueryRef を含めます
ビジュアル名やフィルター名を再利用する	予測できない動作が発生します	一意の ID を生成します
visualType に無効な文字列を設定する	ビジュアルがエラーボックスとして表示されます	powerbi-report-author catalog describe <type> または powerbi-report-author catalog list を実行します
ビジュアルの種類に誤ったロール名を使う	フィールドが無視され、ビジュアルが空白になります	powerbi-report-author catalog describe <type> のロール名に合わせます
Column 型と Measure 型を混在させる	クエリが失敗し、ビジュアルにエラーが表示されます	列には Column、メジャーには Measure を使います
ページを pages.json に追加し忘れる	ページが表示されません	pageOrder 配列に追加します
ブール値を正しい形式で指定しない	型が誤ります	"true" / "false"（接尾辞なし。Value では引用符なし）を使います
数値に型の接尾辞を付けない	型が一致しません	小数には D、整数には L を使います
$schema のバージョンを編集する	PBI Desktop に拒否される場合があります	既存のバージョンを保持します
paragraphs 内で JSON を文字列化する	テキストボックスに何も表示されません	paragraphs はネイティブ JSON 配列です
テキストボックスを細い線や区切り線として使う	height にかかわらず約 24px の高さで表示されます	代わりに shape ビジュアル（長方形）を使います。図形は小さい寸法が反映されます
visualContainerObjects を visual の兄弟要素にする	PBI Desktop でスキーマ検証エラーが発生します	objects の兄弟要素として、visual オブジェクトの内部に置く必要があります
ディメンション列とメジャーをすべて Values に入れて tableEx を使う	DAX でデータの存在が確認されても、ヘッダーは表示される一方でデータ行が表示されません	pivotTable を使い、ディメンションは Rows、メジャーは Values に入れます
PowerShell の ConvertTo-Json でビジュアル JSON を編集する	プロパティの並べ替えや、ネストの深さの切り捨て（-Depth の既定値は 2）が発生します	JSON の操作には Node.js を使うか、必ず -Depth 20 を渡して構造を確認します
JSON ファイルの変更に正規表現や文字列置換を使う	ネスト構造が壊れ、プロパティが兄弟要素の値の中に入り、波括弧の対応が崩れます	ファイルを読み込み → JSON.parse → オブジェクトを変更 → JSON.stringify → 書き戻します。または、完全一致する旧文字列と新文字列を指定して edit ツールを使います
単一系列のグラフでセレクターなしに dataPoint.fill を使う	ツールヒントにデータが表示されるのに、棒や列が見えません	セレクターなしで基本色を指定するには dataPoint.defaultColor を使います。fill には metadata セレクターが必要です
複数系列のグラフで dataPoint.defaultColor を使う	すべての系列／カテゴリが同じ色になり、ビジュアル上で区別できません	ビジュアル間で一貫したパレットを使うにはテーマの dataColors を使います。系列ごとに上書きするには metadata セレクター付きの dataPoint.fill を使います。color-strategy.md § Color Strategy Quick Reference を参照してください
集合横棒／集合縦棒グラフの色が凡例の 1 色にまとまる	ビジュアルに Series ロールがあるのに、すべての棒と凡例マーカーが同じ色合いになります	系列ごとの dataPoint.fill セレクターまたはテーマの dataColors パレットを使います。集合グラフで defaultColor は使わないでください
ビジュアル間でメジャーの色を一致させるために、テーマの dataColors だけに頼る	インデックスによる割り当てが投影順によって変わるため、同じメジャーでもビジュアルごとに色が異なります	メジャーと色の対応表を管理し、ビジュアルごとに明示的な dataPoint.fill／defaultColor を適用します。color-strategy.md § Cross-Visual Measure-Color Consistency を参照してください
メタデータセレクター付きの明示的なメジャーごとの dataPoint.fill に ThemeDataColor を使う	色が警告なしに白または黒になり、期待したパレット色になりません	メタデータセレクターを使った明示的な色の割り当てには Literal の 16 進値を使います。この用途では ThemeDataColor は信頼できません
背景とのコントラストを確認せずに棒／系列の色を選ぶ	ページ／カードの背景に対して棒や線が見えなくなります（例：白いキャンバスに白い棒）	ページと VCO の背景色に対してコントラストがある、彩度の高い中間色から暗色を必ず選びます
ページレベルの background に show プロパティを指定する	スキーマエラーになります。ページの background がサポートするのは color、image、transparency のみです	show を持つのは（ビジュアル上の）VCO の background のみです。ページの背景は常に表示されます
確認せずにドキュメント例からプロパティ名をコピーする	プロパティ名はビジュアルの種類によって異なるため、警告や警告なしの失敗が発生します	正確なプロパティ名を確認するため、必ず powerbi-report-author formatting describe-object <type> <object> を実行します
プロパティがどのオブジェクトに属するか推測する	誤ったオブジェクトを一つずつ確認するため、呼び出しが無駄になります	powerbi-report-author formatting search <type> <regex> を実行し、すべてのオブジェクトを一度に検索します
書式設定プロパティを指定しても効果がない（エラーなし）	cardVisual の枠線で ID セレクターなしに show: false を設定すると、検証には通りますが表示は変わりません	powerbi-report-author formatting describe-object <type> <object> で _selectorHint を確認します。静的エントリと ID セレクターエントリを併用するパターンを使います
単一値のカードで cardCalloutArea を使う	プロパティの検証には通りますが、目に見える効果はありません。cardCalloutArea は複数値のカード（Data にメジャーが 2 つ以上）でのみ表示されます	単一値のカードでは、{ id: "default" } セレクター付きの outline／accentBar／fillCustom を使います。複数値のカードでは、cardCalloutArea がコールアウトタイルごとのスタイルを制御します。card.md § Multi-Value Formatting を参照してください
cardVisual の queryState ロールに "Fields" を使う	バインドを解決できず、PBI Desktop でカードが空白になります。バリデーターは Unknown role "Fields" と Required role "Data" missing を報告します	cardVisual のデータロールは "Data" のみです。"Fields" は旧式の card ビジュアルのロール名なので、引き継がないでください。ロール名は必ず powerbi-report-author catalog describe cardVisual で確認します。card.md § Single-Value Template を参照してください
関連する複数の KPI に対して、単一値の cardVisual インスタンスを個別に作成する	キャンバスのスペースを無駄にし、ビジュアルの種類を誤用します。cardVisual は 1 つのタイル内で複数の投影をネイティブにサポートします	関連する KPI が 2 つ以上求められている場合、すべてのメジャーを Data 投影として含めた 1 つの複数値 cardVisual を既定で使います。カードごとのスタイルを変える必要がある場合に限り、カードを個別に使います。card.md § When to Consolidate vs. Keep Separate を参照してください
ボタンスライサーの Values または Label ロールに複数のフィールドを追加する	各ロールが受け入れるフィールドは 1 つのみのため、スライサーが壊れるか、予期しない結果が表示されます	Values に 1 つ、Label に 1 つのフィールドを入れます。追加フィールドは Tooltips に入れます
スライサーの選択内容を理解するために、他のビジュアルの filterConfig を確認する	スライサーの選択内容は、expansionStates と objects.general.filter を介してスライサー自身の visual.json 内にのみ保存されています。スライサーを変更する場合は、必ず最初に references/slicers.md を読んでください
ソースの種類を確認せずに画像ビジュアルを作成する	URL、ローカルファイル、データフィールドではスキーマや式の種類がそれぞれ異なるため、ビジュアルの構造が誤ります	ビジュアルの作成前に、画像のソース（ローカルファイル／URL／データフィールド）を必ずユーザーに確認します。image.md § Source Types Overview を参照してください
dataCategory: ImageUrl がないフィールドを使って、データにバインドされた画像ビジュアルを作成する	ビジュアルが空白になるか、エラーになります	先に必ずユーザーに警告します。dataCategory: ImageUrl がない場合、ビジュアルは空白になります。他の ImageUrl フィールド、ローカルファイル、URL などの代替案を提示し、作成前に確認します。image.md § Select from data を参照してください
ページのキャンバスに背景画像を配置し、ビジュアルのプロット領域には配置しない	ユーザーがビジュアルと合わせて「背景画像」を求めている（例：「背景画像付きの縦棒グラフ」）のに、画像が visual.objects.plotArea ではなく page.json → objects.background に配置されます	特定のビジュアルに関連して背景画像が求められた場合は、既定で plotArea.image を使います。ページレベルの background.image を使うのは、ユーザーが明示的に「ページ背景」／「キャンバス背景」と指定した場合、またはビジュアルに関する文脈がない場合のみです。image.md § Plot Area Background Image を参照してください
multiRowCard ビジュアルを作成する	旧式の複数行カードは非推奨です。powerbi-report-author validate は PBIR_VISUAL_TYPE_DEPRECATED の警告を出します。「複数カード」「各指標にカード」「メジャーごとにカード」などのユーザーの表現をきっかけに作成されることがよくあります	必ず cardVisual を使います。複数の KPI には、すべてのメジャーを Data ロールの投影として含めた 1 つの複数値 cardVisual を使います。card.md を参照してください
マップビジュアルに azureMap ではなく map や filledMap を使う	旧式の Bing Maps ビジュアルは非推奨であり、作成してはいけません。powerbi-report-author validate は PBIR_VISUAL_TYPE_DEPRECATED の警告を出します	必ず azureMap を使います。map.md を参照してください。マップが描画されない、またはジオコーディングに失敗する場合は、フィールドをデバッグし、別の地理列／座標を試すか、ユーザーに確認します。ユーザーに相談せず、マップ以外のビジュアルに警告なしで置き換えてはいけません
columnAdjustment: growToFit を指定せずに tableEx／pivotTable を作成する	列の幅が内容に合わせて縮まり、未使用の余白が残ります	必ず columnHeaders.columnAdjustment を growToFit に、autoSizeColumnWidth を true に設定します。table.md を参照してください
カスタムのテーブル／マトリックス行の色が反映されない（背景が白い）	既定のスタイルプリセットが objects レベルの backColorPrimary／backColorSecondary を上書きします	カスタム色を使うすべての tableEx／pivotTable で、VCO の stylePreset を 'None' に設定します。table.md § Style Presets を参照してください
暗い VCO 背景なのにテーブルのセルが白い	visualContainerObjects.background が制御するのは外側のコンテナーのみで、テーブルのセルはその上に描画されます	VCO ではなく、objects.values.backColorPrimary/Secondary と objects.columnHeaders.backColor に暗い色を設定します。re-theming.md § Dark Mode Checklist を参照してください
ダークテーマを適用しても、カード／テーブル／スライサーが白いままになる	ダークモードではすべての書式設定の落とし穴が同時に発生します	re-theming.md § Dark Mode Authoring Checklist の手順に従ってください。stylePreset、fillCustom と ID セレクター、objects と VCO の違い、コントラストの確認を網羅しています
Desktop の再読み込み後、テーマ JSON の変更が反映されない	Desktop はテーマファイルをファイル名でキャッシュします	テーマ JSON の名前に短いランダムな接尾辞を付けて変更し、report.json のテーマ登録を更新してから再読み込みします。そうしない場合は、Desktop を終了して再度開きます
sortDefinition を visual 内または visual.json のルートに置く	スキーマ検証エラーが発生し、ソートが警告なしに無視されるため、グラフはアルファベット順に戻ります	sortDefinition は query のプロパティです。visual.query.sortDefinition を使います。visualConfiguration/2.2.0 以降でサポートされています
コンテナー図形の塗りつぶしが参照と一致しない	テキストが見えない、または背景色が誤ります	塗りつぶし色と透明度を参照画像に合わせます。ページの背景ですでに色が付いている場合は、図形自体を省略します。図形を見えないようにする必要がある場合は、テキスト色がページのキャンバスに対して十分なコントラストを保つことを確認します。shape.md § Container Shapes を参照してください
テーマ変更後に図形のテキストが見えなくなる	図形の text オブジェクトに明示的な fontColor がありません。テキストはテーマの前景色を継承しますが、明るいページのキャンバス上で fill が明るい色（白いピル／ボタンなど）の場合、継承された暗い前景色が描画されない、または塗りつぶしがキャンバスに溶け込み、テキストが見えなくなります	図形の text オブジェクトには、{ selector: { id: "default" } } エントリ内で明示的な fontColor を必ず設定します。テーマ変更時は text.show: true のすべての図形を監査してください。16 進値の一括置換では、新しい fontColor プロパティの追加が必要な図形を見落とします
ゼロまたは負の値を含むデータで logAxisScale を有効にする	PBI Desktop は警告を出して、警告なしに線形スケールに戻ります。ゼロまたは負の値の対数は定義されていません	適用前に必ずユーザーに警告します。ask_user を使って、負の値をフィルターする、メジャーを変更する、labelDisplayUnits を使うなどの代替案を提示します。ユーザーが負の値を解決するか、バインドされる値がすべて正であると確認した後にのみ logAxisScale: true を適用します。cartesian.md § Log Scale を参照してください
インラインの上書きを一括更新せずにテーマを変更する	カスケードの優先度 2 にあるハードコードされた Literal の 16 進値にはテーマのみの変更が反映されず、図形、ページの背景、ナビゲーションボタン、テキストボックスに古い色が残ります	レポートにビジュアルごとの色の上書きがある場合は、re-theming.md § Re-theming Workflow のステップ 0〜3 に従います。色の対応表を作成し、テーマ JSON を更新してから、再読み込み前に definition/ ファイル内の古い 16 進値を一括更新します
一括更新せずにテーマの dataColors だけを変更する	図形、アクセントバー、ナビゲーションボタンの枠線には古いアクセント色が残ります。ThemeDataColor の参照ではなく、古い dataColors 配列のハードコードされた Literal の 16 進値を使っているためです	definition/ ファイル内にある、古い dataColors[N] の 16 進値をすべて一括更新します。同じ色調のまま「アクセント／データ色だけを変更する」依頼でも、完全な一括更新が必要です。図形やナビゲーション要素では、dataColors[0] がアクセントの塗りつぶし／枠線としてハードコードされていることがよくあります

公式ドキュメント

Microsoft Learn のセットアップガイダンス、サポート対象の制約、機能の提供状況については、Power BI レポート作成ドキュメントをご覧ください。