pbip

PBIP プロジェクト形式

PBIP（Power BI Project）は、Power BI の開発者モード用ファイル形式です。.pbix バイナリをフォルダー内に整理された人間が読めるテキストファイルに分解することで、ソース管理、外部での編集、複数の作成者による共同作業が可能になります。

全般に関する重要なガイダンス

• このスキルの対象はプロジェクト構造であり、レポートの編集ではありません。 セマンティックモデルには te を、レポートの変更にはすべて pbir を使用してください。PBIR JSON を手作業で編集しないでください。
• PBIX はブラックボックス、PBIP は透明です。 PBIX は差分比較や外部編集ができない単一のバイナリです。PBIP は同じコンテンツをテキストファイルに分割します。PBI Desktop の「ファイル」＞「名前を付けて保存」で相互に変換できます。
• シックレポートとシンレポート： シックレポートは、同じプロジェクト内に .Report/ と .SemanticModel/ をまとめます（definition.pbir は byPath を使用します）。シンレポートには .Report/ のみがあり、byConnection を介してリモートモデルに接続します。管理された BI や共有 BI には、シンレポートが推奨されます。
• 1 つのプロジェクトに複数のアイテムを含められます。 複数の .Report/ フォルダーと .SemanticModel/ フォルダーが共存できます。.pbip ファイルは省略可能です。definition.pbir を直接開いてください。
• BOM なしの UTF-8 を使用してください。 すべてのファイルは BOM なしの UTF-8 として保存する必要があります。先頭に BOM があると、一部のツールで解析エラーが発生します。
• Git の改行コード： PBI Desktop は CRLF を書き込みます。正規化するには、.gitattributes で core.autocrlf または * text=auto を設定してください。
• Windows のパス長制限は 260 文字です。 ルートパスは短くしてください。ページやビジュアルの GUID を深くネストすると、この制限を超える場合があります。
• Desktop の再読み込みは選択的です。 サポートされているレポートやモデルの変更には pbir desktop refresh を使用してください。テーマを変更した場合は、Desktop を閉じて再度開いてください。
• 名前の変更は複数の箇所に影響します。 te mv --save でモデルオブジェクトの名前を変更した後、pbir fields replace または replace-table で各レポートを更新し、両方を検証してください。
• SparklineData メタデータのセレクターは、標準的な SourceRef.Entity JSON 構造に従わない簡潔な文字列に Entity 参照を埋め込みます。見落としやすい点に注意してください。
• DAX クエリファイルは 2 か所にあります： <Name>.SemanticModel/DAXQueries/ と <Name>.Report/DAXQueries/ です。名前を変更する際は、必ず両方を確認してください。

PBIX ファイルの取り扱い

PBIX は不透明な Desktop 成果物として扱ってください。解凍したり、内部を改変したり、その内容から PBIR を再構築したり、承認されていない抽出エンジンを呼び出したりしないでください。サードパーティ製エンジンの再配布に関する Microsoft のライセンス／EULA の問題は、このプロジェクトでは未解決です。

Power BI Desktop の **「ファイル」＞「名前を付けて保存」＞「Power BI Project（.pbip）」**を使用し、生成された .Report フォルダーには pbir を、セマンティックモデルには te を使用してください。Desktop での変換が利用できない場合は、変換方法を独自に考案せず、作業を中止して PBIP／PBIR のソース成果物を依頼してください。

PBIX と PBIP の比較

項目	PBIX	PBIP
形式	単一のバイナリファイル	テキストファイルのフォルダー
ソース管理	差分比較に不向き	Git 対応で、人が読める差分
共同作業	一度に 1 人の作成者	複数の作成者に対応し、マージしやすい
外部編集	サポート対象外	VS Code、Tabular Editor、スクリプト
デプロイ	「ファイル」＞「発行」	Git 統合、Fabric API、fabric-cicd
データ	キャッシュデータを含む	cache.abf は Git の追跡対象外。Git にはメタデータのみ
変換	「ファイル」＞「名前を付けて保存」＞「PBIP」	「ファイル」＞「名前を付けて保存」＞「PBIX」

プロジェクト構造

PBIP では .Report/ フォルダーが必須です。.SemanticModel/ フォルダーは省略可能です。シンレポートには .Report/ のみがあり、definition.pbir の byConnection を介してリモートのセマンティックモデルを参照します。

両方のアイテムにある .pbi/ サブフォルダー（localSettings.json、editorSettings.json、cache.abf など）はすべて省略可能です。これらは Power BI Desktop が生成する、ユーザーやコンピューターごとのランタイム状態です。外部ツールで新規作成された PBIP にはこれらが一切含まれない場合がありますが、それでもプロジェクトは Desktop で問題なく開きます。

<ProjectName>/
+-- <Name>.pbip                              # Entry point (references .Report folder) — optional
+-- .gitignore                               # Recommended; excludes .pbi/localSettings.json and cache.abf
+-- <Name>.SemanticModel/                    # OPTIONAL — absent for thin reports
|   +-- .pbi/                                # All contents OPTIONAL, per-user runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   |   +-- editorSettings.json              # Editor settings (committed)
|   |   +-- cache.abf                        # Data cache (gitignored)
|   |   +-- unappliedChanges.json            # Pending Power Query changes
|   |   +-- daxQueries.json                  # DAX query view tab settings
|   |   +-- tmdlscripts.json                 # TMDL view script tab settings
|   +-- definition.pbism                     # SM entry point (required if .SemanticModel exists)
|   +-- definition/                          # TMDL format (preferred) — see tmdl skill
|   +-- model.bim                            # TMSL format (legacy alt to definition/, mutually exclusive)
|   +-- diagramLayout.json                   # SM diagram (no external edit)
|   +-- DAXQueries/                          # .dax files from DAX query view
|   +-- TMDLScripts/                         # .tmdl files from TMDL view
|   +-- Copilot/                             # Copilot tooling metadata
|   +-- .platform                            # Fabric identity (displayName, logicalId)
+-- <Name>.Report/                           # REQUIRED
|   +-- .pbi/                                # OPTIONAL runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   +-- definition.pbir                      # Report entry point (required for PBIR format)
|   +-- definition/                          # PBIR format — see pbir-format skill
|   |   +-- report.json
|   |   +-- version.json
|   |   +-- pages/
|   |   |   +-- pages.json
|   |   |   +-- <page-slug>/                 # See "Page folder naming" below
|   |   |   |   +-- page.json
|   |   |   |   +-- visuals/...
|   +-- report.json                          # PBIR-Legacy format (legacy alt to definition/)
|   +-- mobileState.json                     # Mobile layout (no external edit)
|   +-- semanticModelDiagramLayout.json      # Diagram positions (table renames)
|   +-- CustomVisuals/                       # Private custom visual metadata
|   +-- StaticResources/
|   |   +-- SharedResources/                 # Base themes, shared resources
|   |   |   +-- BaseThemes/<name>.json       # Resolution path: <report>/StaticResources/SharedResources/<item.path>
|   |   +-- RegisteredResources/             # Custom themes, images, .pbiviz files
|   +-- DAXQueries/                          # .dax files from report DAX query view
|   +-- .platform                            # Fabric identity

ページフォルダーの命名

Power BI Desktop では、新しいページ、ビジュアル、ブックマーク、フィルターのフォルダーに、デフォルトで判読しにくい20文字の16進数スラッグが使われます（例：847663d71e27e0840063）。Microsoft のドキュメントによると、これらは分かりやすい名前に変更できますが、変更後の名前は次の条件を満たす必要があります。

• 正規表現： ^[\w-]+$ — 単語文字（英字、数字、アンダースコア）またはハイフンのみ。
• スペース、ピリオド、その他の句読点は使用できません。 この条件に合わない名前は Power BI Desktop に黙って無視され、読み込んだレポートからページやビジュアルが消えます。エラーダイアログが表示されないため、これは診断が最も難しい種類のバグです。
• フォルダー名と name フィールドは完全に一致している必要があります（大文字と小文字を区別します）。 フォルダー名にはサフィックスを付けない形式（<slug>/）と、サフィックスを付ける形式（<slug>.Page/）があり、どちらもディスク上では有効です。pbir-cli の CLI パス構文では .Page サフィックスを使いますが、現在の Desktop の保存ではサフィックスは省略されます。
• pages.json.pageOrder の項目では、表示名ではなくスラッグを参照する必要があります。 activePageName は pageOrder の項目のいずれかでなければなりません。
• 外部で名前を変更した後は、Desktop を再起動してください。 PBI Desktop は起動中にファイルの変更を検出しません。

ページの名前は pbir pages rename で変更してください。このコマンドがレポート内の参照もまとめて更新します。 フォルダーの名前変更や、関連する JSON の手作業による修正はしないでください。

SharedResources のパス解決

resourcePackages[] に記載された項目は、次を基準に解決されます。

<Report>/StaticResources/<package_type>/<item.path>

SharedResources パッケージに { "path": "BaseThemes/Fluent2-CY26SU03.json" } という項目がある場合、Power BI Desktop は次の場所を探します。

<Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json

リソースファイルが見つからないことは、よくある重大なエラーです。 report.json で themeCollection.baseTheme.type = "SharedResources" が宣言され、ディスク上に存在しないリソースが指定されている場合、レポートを開けません。validate_pbip.py はこれを明示的にチェックします。

よくあるタスクで読むもの

タスク	読むもの
PBIX ソースを変換する	上記のPBIX ファイルの操作 — Desktop の「名前を付けて保存」を使います。抽出は不要です
エントリーポイントのファイル構造を理解する	references/pbip-file-types.md — .pbip、.pbir、.pbism、.platform の JSON 構造、バージョンプロパティ、byPath と byConnection
テーブル、メジャー、または列の名前を変更する	te mv --save を実行してから、pbir fields replace または replace-table を実行します。検証範囲を理解する場合にのみ、リファレンスを参照してください
PBIP プロジェクトをフォーク／複製する	references/pbip-file-types.md — .pbip のパス、.pbir の byPath、.platform の logicalId と displayName を更新します
Copilot のツールファイルを操作する	references/copilot-folder.md — AI 向けの指示、検証済みの回答、スキーマ、プロンプトの例
TMDL モデルファイルを編集する	tmdl スキル — 構文、作成方法、列のプロパティ、命名規則
PBIR レポートを変更する	pbir-cli スキル — レポートの変更全般。pbir-format は読み取り専用のスキーマ情報です
名前変更後に参照切れがないことを確認する	以下の Grep コマンド

PBIP プロジェクトのフォーク

1. プロジェクトフォルダーをコピーする — ルートフォルダー全体を新しい名前で複製します。
2. アーティファクトのフォルダー名を変更する — .Report/ と .SemanticModel/ のサブフォルダーを、新しいプロジェクト名に合わせて変更します。
3. .pbip の名前を変更して更新する — .pbip ファイルの名前を変更し、artifacts[].report.path を変更後の .Report フォルダーを指すように更新します。
4. .pbir を更新する — レポートで byPath を使用している場合は、変更後の .SemanticModel フォルダーを指すようにパスを更新します。
5. .platform ファイルを更新する — 各 .platform ファイルの displayName に新しいプロジェクト名を設定します。別個の Fabric アイテムとしてデプロイする場合は、logicalId（新しい GUID）を再生成します。

検証

組み合わせて使用する、検証用のツールが2つあります。

1. scripts/validate_pbip.py — 横断的な項目を検証するプロジェクトレベルのバリデーターです。.pbip のルートファイル、.platform の ID、セマンティックモデルの形式（TMDL と TMSL）、datasetReference の解決、ディスク上のテーマリソースの解決、孤立したページフォルダー、およびページ名のサイレント無視正規表現ルール（^[\w-]+$ に該当しないページ名は Power BI Desktop でサイレントに無視されます）を確認します。PATH 上に pbir validate があれば、.Report の詳細なスキーマ検証を委任します。

   python3 scripts/validate_pbip.py <path-to-.pbip-or-project>           # validate
   python3 scripts/validate_pbip.py <path> --fix                         # scaffold .gitignore
   python3 scripts/validate_pbip.py <path> --json                        # machine-readable
   python3 scripts/validate_pbip.py <path> --no-pbir-cli                 # skip delegation
   

   終了コード：0 問題なし、1 警告のみ、2 エラー、3 使用方法のエラー。

2. pbir validate <Report.Report>（pbir-cli スキルから）— .Report フォルダーの標準的な JSON スキーマおよび PBIR 構造バリデーターです。JSON 構文、スキーマへの準拠、必須フィールド、およびオプションの --qa／--fields／--strict チェックを確認します。

3. pbip-validator エージェント — 名前変更後の孤立した参照を対話形式で LLM に検証させる場合など、決定論的なレポートではなくプロジェクト全体を推論する必要がある場合に使用します。

pbir validate の既知の注意点： プロジェクトの .pbi/localSettings.json が pbir-cli に同梱されているものより新しいスキーマバージョンを使用している場合、pbir validate は SCHEMA_UNSUPPORTED を返します。不足しているスキーマを必要に応じて取得できるよう --allow-download-schemas を指定するか、.pbi/ ファイルを無視してください（ユーザーごとのランタイム状態であり、コミット対象の定義には含まれません）。

名前変更またはフォーク操作の後は、古い参照が残っていないことを確認してください。

# Search for old name across all project files
grep -r "Old Name" "Project.Report/" "Project.SemanticModel/" --include="*.json" --include="*.tmdl" --include="*.dax"

# Search with word boundaries to avoid partial matches
grep -rP "\bOld Name\b" "Project.Report/" "Project.SemanticModel/"

# Look for old name in single-quoted DAX references
grep -r "'Old Name'" --include="*.tmdl" --include="*.dax"

見落としやすい場所：

1. SparklineData のメタデータ — 標準的な JSON 構造の外にあるコンパクトな文字列形式
2. 条件付き書式の式 — Conditional.Cases 内にネストされた Entity 参照
3. フィルター設定 — filterConfig セクション内のページレベルおよびビジュアルレベルのフィルター
4. 並べ替え定義 — ビジュアル JSON 内の sortDefinition ブロック
5. Report フォルダー内の DAX クエリ — 2 番目の DAX クエリの場所
6. カルチャーファイルの linguisticMetadata — 埋め込み JSON 内の ConceptualEntity と ConceptualProperty

関連スキル

このプラグイン内：

• tmdl — .tmdl ファイルを直接編集するための TMDL 構文、作成方法、編集ルール
• pbir-format — PBIR JSON 形式、visual.json、テーマ、フィルター、レポート拡張機能

その他のプラグイン：

• semantic-models プラグイン — セマンティックモデル開発のためのツールとワークフロー（命名規則、モデル品質）。ファイル形式だけでなく、実際のモデルの内容を扱う場合に使用します。
• pbi-desktop プラグイン — TOM／ADOMD.NET を介して Power BI Desktop のローカル Analysis Services インスタンスに接続します。
• tabular-editor プラグイン — Tabular Editor CLI、C# スクリプト、BPA ルール、ドキュメント検索

参考資料

プロジェクト構造：

• references/pbip-file-types.md — エントリーポイントのファイル構造（.pbip、.pbir、.pbism、.platform）、.pbi/ サブフォルダー、DAXQueries/、TMDLScripts/、model.bim、.gitignore、バージョンプロパティ、JSON の例
• references/copilot-folder.md — Copilot/ フォルダーの構造（AI 向けの指示、検証済みの回答、スキーマ、プロンプトの例）

名前変更操作：

• references/rename-cascade.md — 名前変更の各連鎖箇所についての詳細な変更前／変更後の例（TMDL とレポートファイル）

ドキュメントの取得： 最新の PBIP リファレンスドキュメントを取得するには、https://learn.microsoft.com を検索して該当ページを取得してください。ユーザーのリクエストに基づいて検索し、作業を進める前に十分なコンテキストを得られるよう、必要に応じて複数回検索してください。

外部資料：

• PBIP の概要（Microsoft Learn）
• セマンティックモデルフォルダー（Microsoft Learn）
• レポートフォルダー（Microsoft Learn）