validation-testing

Power BI の検証とセルフテスト

概要

開発者（または Claude）が生成する TMDL、PBIR、DAX、M のあらゆる成果物を検証するスキルです。目的は、Fabric REST へのデプロイに失敗する前に、構文、スキーマ、ベストプラクティスに関するエラーをローカルで検出することです。このスキルは、powerbi-expert エージェントのセルフ検証プロトコルに不可欠です。エージェントが TMDL または PBIR を作成する場合は、このスキルにある対応する検証手順を説明するか、実行してください。

2026 年現在、Power BI の検証には、それぞれ異なる種類のエラーを検出する 4 つのレイヤーがあります。

レイヤー	TMDL ツール	PBIR ツール	検出する内容
1. 構文／パーサー	TmdlSerializer.DeserializeDatabaseFromFolder（.NET）	JSON スキーマ検証（$schema URL）	インデントエラー、無効なキーワード、不正な形式の JSON
2. オブジェクト／スキーマ	TmdlSerializer -> TmdlSerializationException（構文は有効、TOM メタデータは無効）	microsoft/json-schemas リポジトリ内の PBIR JSON スキーマ	無効なプロパティの組み合わせ、型の不一致、必須プロパティの不足
3. ベストプラクティス（BPA）	Tabular Editor の BPA ルール（BPARules.json）または semantic-link-labs.run_model_bpa	PBI-InspectorV2 のルール（Base-rules.json）	アンチパターン、表示フォルダーの不足、曖昧なリレーションシップ、命名規則
4. リネージ／相互参照	DAX メジャーの参照先が解決されること、sortByColumn の存在、計算グループの優先順位	ブックマークが実在するページを参照していること、ドリルスルー先が存在すること、テーマファイルがあること	孤立した参照、壊れたブックマーク、ビジュアルの不足

基本原則： レイヤー 1 と 2 に合格せずにデプロイしてはいけません。レイヤー 3 に合格せずに main にマージしてはいけません。

2026 年の検証ツールの概要

ツール	検証対象	ランタイム	ステータス
TmdlSerializer (Microsoft.AnalysisServices.Tabular)	TMDL 構文 + TOM スキーマ	.NET / pythonnet	GA
Tabular Editor 2 CLI (無料)	TMDL の読み込み + BPA + カスタム C# スクリプト	.NET CLI	GA、無料
Tabular Editor 3 CLI (有料)	同上 + 高度なルール + DAX デバッガー	.NET CLI	GA、商用
semantic-link-labs.run_model_bpa	Python からの TMDL/TOM モデル BPA	Fabric ノートブック（Python）	GA、約 60 の組み込みルール
semantic-link-labs.run_model_bpa_bulk	ワークスペース内のすべてのモデルの BPA	Fabric ノートブック	GA
PBI-InspectorV2 ("Fab Inspector")	PBIR / PBIP / Fabric アイテムのルール	.NET CLI / Docker	v2.3 以降、GA
pbi-tools	PBIX の抽出／コンパイル + 基本的な TMDL	.NET CLI	TMDL は安定、PBIR は開発中
fabric-cicd (組み込み)	デプロイ前の parameter.yml + リポジトリ構造	Python	GA
DaxFormatter API	DAX 構文	HTTP	GA
Microsoft TMDL VS Code 拡張機能	エディター内の TMDL 構文	VS Code	GA
コミュニティ製 CPIM.TMDL-language-support	TMDL + DAX + M のセマンティックハイライト	VS Code	GA
INFO DAX 関数	ライブモデルのイントロスペクション（DMV を置き換え）	XMLA / Desktop	GA

セルフ検証プロトコル（生成された成果物向け）

エージェントのループ内で TMDL または PBIR の成果物を生成する場合は、次の最低限の手順に従ってください。

1. ファイルを書き込む前 -- 構造を頭の中で検証します。すべてのオブジェクト参照が解決でき、すべての必須プロパティが設定されている必要があります。
2. ファイルを書き込んだ後 -- 構文レベルの解析を実行します（TMDL には TmdlSerializer、PBIR には JSON スキーマ検証）。
3. デプロイを提案する前 -- BPA を実行します（Tabular Editor CLI または semantic-link-labs）。
4. 結果をその場で報告 -- 検証エラーを黙って無視してはいけません。行番号、ファイルパス、失敗したルールを明示してください。

50 行の TMDL メジャーブロックを生成するエージェントの応答には、必ず次のいずれかを続けてください。

• (a) ユーザーが貼り付けて実行できる検証スクリプト、または
• (b) 環境が対応している場合は、Bash／PowerShell／Python によるインラインの検証コマンド

TMDL の検証 — レイヤー 1（構文パーサー）

最も高速で、依存関係が最も少ない TMDL 構文チェックには、TmdlSerializer.DeserializeDatabaseFromFolder を使います。次の例外がスローされます。

• TmdlFormatException — TMDL テキストの構文が無効です（不正なキーワード、誤ったインデント、不正な形式の式など）。正確な場所を示す Document、Line、LineText プロパティが含まれます。
• TmdlSerializationException — TMDL テキストは解析されますが、無効な TOM メタデータが生成されます（例：column が存在しない dataType を参照している、または partition が不明なデータソースを参照している場合）。

最小限の C# バリデーター（.NET 8）：

using Microsoft.AnalysisServices.Tabular;
using Microsoft.AnalysisServices.Tabular.Tmdl;

string folder = args[0];
try
{
    var db = TmdlSerializer.DeserializeDatabaseFromFolder(folder);
    Console.WriteLine($"OK: TMDL parsed. CompatLevel={db.CompatibilityLevel}, Tables={db.Model.Tables.Count}");
    return 0;
}
catch (TmdlFormatException fx)
{
    Console.Error.WriteLine($"SYNTAX ERROR  {fx.Document}:{fx.Line}");
    Console.Error.WriteLine($"  {fx.LineText}");
    Console.Error.WriteLine($"  -> {fx.Message}");
    return 1;
}
catch (TmdlSerializationException sx)
{
    Console.Error.WriteLine($"METADATA ERROR  {sx.Document}:{sx.Line}");
    Console.Error.WriteLine($"  {sx.Message}");
    return 2;
}

Tabular Editor 2 CLI を使ったワンライナー（C# プロジェクトは不要）：

# Loads TMDL folder; non-zero exit on parse failure
TabularEditor.exe "MyProject.SemanticModel/definition" -B "MyProject.bim"

-B（bim 出力）スイッチを指定すると、逆シリアル化と再シリアル化のラウンドトリップが実行されます。解析に失敗すると、エラーが stderr に出力され、終了コードが 0 以外になります。

スクリプトでの完全な例や Python 版については、references/tmdl-validation-recipes.md を参照してください。

TMDL の検証 — レイヤー 3（ベストプラクティスアナライザー）

Best Practice Analyzer（BPA）は、テーブル形式のモデルでアンチパターンをチェックする標準的なツールです。Tabular Editor 2、Tabular Editor 3、semantic-link-labs、および Fabric > Workspace settings > Best Practice Analyzer で同じエンジンが使われています。

Tabular Editor 2 CLI（無料、CI におすすめ）：

# Run BPA against a TMDL folder using the official Microsoft rule set
TabularEditor.exe "MyProject.SemanticModel/definition" \
  -A "https://raw.githubusercontent.com/TabularEditor/BestPracticeRules/master/BPARules.json" \
  -V \
  -G

# Exit codes:
#   0 = no violations
#   1 = warnings only
#   2 = errors found (any rule with Severity >= 3) -- pipeline should FAIL

CI/CD で重要なスイッチ：

スイッチ	用途
-A <rules.json>	指定したルールファイル（URL またはローカルパス）で BPA を実行します
-V	詳細な出力（各違反を一覧表示）
-G	GitHub Actions / Azure Pipelines のログ形式（セクションのグループ化、ファイルパス）
-D <conn>	BPA 合格後にデプロイします
-S <script>	BPA の前に C# スクリプトを実行します（カスタム検証）

重大度に基づく失敗： BPA ルールが Error（レベル 3）に設定されている場合、CLI は直ちに停止し、終了コードが 0 以外になります。PR をブロックする必要があるアンチパターンには BPA ルールを Error の重大度に設定し、助言のみのルールには Warning を設定してください。

標準の Microsoft ルールセット： TabularEditor/BestPracticeRules — パフォーマンス、エラー防止、DAX、メンテナンス、命名に関する約 60 個のルールが含まれています。CI では必ず特定のコミットに固定してください。

BPA ルールの完全なリファレンス（Microsoft の全ルールの解説とカスタムルールの作成方法）については、references/bpa-rules-reference.md を参照してください。

Python からの TMDL 検証（semantic-link-labs）

%pip install semantic-link-labs -q
import sempy_labs as labs

# Run the default BPA against a deployed model
results = labs.run_model_bpa(
    dataset="SalesModel",
    workspace="Sales-Dev",
    extended=True,        # adds VertiPaq Analyzer stats for performance rules
)
results.head(20)

# Run BPA against every model in a workspace and store to delta
labs.run_model_bpa_bulk(
    workspace="Sales-Dev",
    extended=True,
)

# Custom rule set from a JSON file in the lakehouse
my_rules = labs.model_bpa_rules()  # built-in rule definitions
my_rules.append({
    "ID": "AVOID_AUTO_DATE",
    "Name": "Disable auto date/time",
    "Category": "Performance",
    "Severity": 3,
    "Scope": "Model",
    "Expression": "DiscourageImplicitMeasures and not AutoDateTime",
})
labs.run_model_bpa(dataset="SalesModel", rules=my_rules)

semantic-link-labs は、レイヤー 3 で Python を使う方法です。Fabric ノートブック、スケジュールされた BPA 実行、Spark パイプライン内で使用してください。ローカルフォルダーからオフラインで TMDL を解析する方法を含む、Python 検証の手順については、references/tmdl-validation-recipes.md を参照してください。

PBIR の検証 — レイヤー 1（JSON スキーマ）

すべての PBIR ファイルには、microsoft/json-schemas にある Microsoft 公式スキーマを指す $schema URL が埋め込まれています。そのため、どの JSON スキーマバリデーターでも、PBIR ファイルの構文をローカルでチェックできます。

Python jsonschema バリデーター：

import json
import urllib.request
from pathlib import Path
from jsonschema import Draft202012Validator, RefResolver

def validate_pbir_file(pbir_file: Path) -> list[str]:
    doc = json.loads(pbir_file.read_text(encoding="utf-8"))
    schema_url = doc.get("$schema")
    if not schema_url:
        return [f"{pbir_file}: no $schema declared"]

    schema = json.loads(urllib.request.urlopen(schema_url).read())
    validator = Draft202012Validator(schema)
    errors = sorted(validator.iter_errors(doc), key=lambda e: e.path)
    return [f"{pbir_file}#{'/'.join(map(str, e.path))}: {e.message}" for e in errors]

# Walk the entire PBIR folder
report_root = Path("MyProject.Report/definition")
all_errors = []
for f in report_root.rglob("*.json"):
    all_errors.extend(validate_pbir_file(f))

if all_errors:
    print(f"FAIL: {len(all_errors)} schema violations")
    for e in all_errors[:50]:
        print(f"  {e}")
    raise SystemExit(1)
print(f"OK: validated {sum(1 for _ in report_root.rglob('*.json'))} PBIR files")

オフライン CI 用にスキーマをローカルにキャッシュします： git clone https://github.com/microsoft/json-schemas.git を一度実行し、その後 RefResolver がローカルコピーを参照するように設定します。これにより、ビルドのたびに CI が 1000 回以上の HTTP 呼び出しを行うのを防げます。

PBIR 検証 — レイヤー 3（PBI-InspectorV2 / Fab Inspector）

NatVanG/PBI-InspectorV2（Fab Inspector としても知られています）は、標準的なルールベースの PBIR/PBIP バリデーターです。v2.3 以降では、-fabricitem スイッチと新しい PBIR 拡張形式により、すべての Fabric アイテムタイプ（セマンティックモデル、レポート、ノートブック、レイクハウス）をサポートします（元の PBI-Inspector リポジトリは PBIR-Legacy のみを処理します）。

インストール（クロスプラットフォーム対応の .NET ツール）：

# Download the latest release from https://github.com/NatVanG/PBI-InspectorV2/releases
# Or use the published Docker image
docker pull natvang/pbi-inspector-v2:latest

PBIP フォルダーを対象に実行：

PBIInspectorCLI \
  -fabricitem "./MyProject.Report" \
  -rules "./pbi-inspector-rules.json" \
  -formats "JSON,HTML,GitHub" \
  -output "./inspector-results"

# Exit codes:
#   0 = all rules passed
#   1 = warnings only
#   2 = at least one Error-severity rule failed

ルール形式 — Base-rules.json をベースにしてカスタマイズします。各ルールには次の項目があります。

• Name（表示名）
• Description
• LogType（Error / Warning / Info）
• Disabled（削除せずにスキップ）
• Path（PBIR ファイル内の JSONPath）
• Test（isEqualTo、isGreaterThan、isLessThan、mustExist、mustNotExist、regex などのいずれか）

すべての PBIR PR で適用する一般的なルール：

[
  {
    "Name": "All visuals have a title",
    "LogType": "Error",
    "Path": "$.visual.objects.title[0].properties.show.expr.Literal.Value",
    "Test": "isEqualTo",
    "Expected": "true"
  },
  {
    "Name": "Page count under limit",
    "LogType": "Error",
    "Path": "$.pages",
    "Test": "arrayLengthLessThan",
    "Expected": 1000
  },
  {
    "Name": "Bookmarks reference real pages",
    "LogType": "Error",
    "Path": "$.children[?(@.targetSection)].targetSection",
    "Test": "mustResolveToPage"
  }
]

ルールの詳しい例と CI ゲートのパターンについては、references/pbir-validation-recipes.md を参照してください。

Fabric CI/CD、DAX、リネージ、CI ゲート、エラーカタログ

fabric-cicd のデプロイ前検証、サーバーを使用しない DAX 構文検証、リネージ／相互参照検証に特化したレシピは、references/fabric-dax-lineage-validation.md にあります。GitHub Actions の CI ゲートパターン、一般的なエラーの対応表、静的検証の制限については、references/ci-gates-and-error-catalog.md を参照してください。

追加リソース

リファレンスファイル

• references/tmdl-validation-recipes.md — TMDL 検証の完全ガイド：TmdlSerializer の C# パターン、Python の pythonnet ラッパー、Tabular Editor の C# スクリプト、INFO DAX によるイントロスペクション、オフライン解析
• references/pbir-validation-recipes.md — PBIR JSON スキーマ検証、PBI-InspectorV2 のルール例、リネージ相互参照リンター、GitHub Actions との統合
• references/bpa-rules-reference.md — Microsoft 標準 BPA ルールセットの概要、ルール作成ガイド、重大度の方針、バージョン固定のレシピ
• references/fabric-dax-lineage-validation.md — fabric-cicd、DAX 構文、リネージ検証のレシピ
• references/ci-gates-and-error-catalog.md — CI ゲートのパターン、一般的な検証エラー、静的検証の制限

関連スキル

• powerbi-master:tmdl-mastery — TMDL 構文リファレンス（TMDL を生成するときに使用し、検証する際はこちらに戻ってきてください）
• powerbi-master:programmatic-development — PBIR 生成（PBIR を生成するときに使用し、検証する際はこちらに戻ってきてください）
• powerbi-master:performance-optimization — DAX Studio、VertiPaq Analyzer、Performance Analyzer を使った実行時検証

公式 2026 リファレンス

• TmdlSerializer クラス（Microsoft Learn）
• TmdlFormatException クラス（Microsoft Learn）
• Tabular Editor BPA ドキュメント
• TabularEditor/BestPracticeRules（Microsoft 公式ルールセット）
• NatVanG/PBI-InspectorV2（Fab Inspector）
• semantic-link-labs ベストプラクティスアナライザー
• microsoft/json-schemas（PBIR 公式 JSON スキーマ）
• fabric-cicd のパラメーター化