---

name: bpa-rules description: This skill should be used when the user asks to "create a BPA rule", "write a Best Practice Analyzer rule", "improve a BPA expression", "fix expression for BPA", "analyze BPA annotations", "check model for best practices", "audit BPA rules", "discover BPA rules", "list all BPA rules", "validate BPA rules", or mentions Tabular Editor BPA rules. Provides guidance for creating, improving, auditing, and understanding Best Practice Analyzer rules for Power BI semantic models.

Best Practice Analyzer Rules

Expert guidance for creating and improving BPA (Best Practice Analyzer) rules for Tabular Editor and Power BI semantic models.

When to Use This Skill

Activate automatically when tasks involve:

• Creating new BPA rules for semantic model validation
• Improving or debugging BPA rule expressions
• Writing FixExpression to auto-remediate rule violations
• Understanding BPA annotations in TMDL files
• Analyzing a semantic model against best practices
• Converting ad-hoc checks into reusable BPA rules
• Auditing or discovering all BPA rules across sources (built-in, URL, model, user, machine)

Critical

• Always validate rule expressions before suggesting them
• Test expressions against the target scope (Measure, Column, Table, etc.)
• Ensure FixExpression does not cause data loss or break the model
• Consider CompatibilityLevel when using newer TOM properties

Tabular Editor Compatibility

BPA rule files must follow specific formatting requirements for Tabular Editor to load them correctly. Files that don't follow these rules may show empty rule collections or fail to load entirely.

Line Endings (CRLF Required)

Tabular Editor on Windows requires Windows line endings (CRLF, \r\n). Files with Unix line endings (LF only) will fail to load or show empty rule collections.

To convert a file to CRLF:

Copy# macOS/Linux
sed -i 's/$/\r/' rules.json

# Or use the validation script
python scripts/validate_rules.py --fix rules.json

File Paths

When adding rule files in Tabular Editor:

• Use absolute paths (e.g., C:\BPARules\my-rules.json)
• Avoid relative paths with ..\..\.. - TE may fail to resolve these
• URLs work reliably (e.g., https://raw.githubusercontent.com/...)

JSON Format Requirements

No extra properties: TE's JSON parser is strict. Only use allowed fields:

• ID, Name, Category, Description, Severity, Scope, Expression
• FixExpression, CompatibilityLevel, Source, Remarks

Avoid these patterns:

Copy// BAD: _comment fields not allowed
{ "_comment": "Section header", "ID": "RULE1", ... }

// BAD: Runtime fields (TE adds these, don't include them)
{ "ID": "RULE1", "ObjectCount": 0, "ErrorMessage": null, ... }

// GOOD: FixExpression can be null or omitted
{ "ID": "RULE1", "FixExpression": null, ... }
{ "ID": "RULE1", "Name": "...", "Severity": 2, "Scope": "Measure", "Expression": "..." }

Note: FixExpression: null is valid. ErrorMessage and ObjectCount are runtime fields that TE adds - do not include them in rule definitions.

Regex Expression Syntax

When using RegEx.IsMatch() in expressions:

No @ prefix: Do not use C# verbatim string prefix

Copy// BAD: @ prefix not supported
RegEx.IsMatch(Expression, @"FILTER\s*\(\s*ALL")

// GOOD: Standard escaping
RegEx.IsMatch(Expression, "FILTER\\s*\\(\\s*ALL")

No RegexOptions parameter: TE doesn't support the options parameter

Copy// BAD: RegexOptions not supported
RegEx.IsMatch(Name, "^DATE$", RegexOptions.IgnoreCase)

// GOOD: Use inline flag or pattern only
RegEx.IsMatch(Name, "(?i)^DATE$")
RegEx.IsMatch(Name, "^(DATE|date|Date)$")

Correct Scope Names

Use the exact scope names from the TOM enum. Common mistakes:

Note: Column is valid as a backwards-compatible alias for DataColumn, CalculatedColumn, CalculatedTableColumn.

Validation Script

Use the validation script to check and fix TE compatibility issues:

Copy# Check for issues
python scripts/validate_rules.py rules.json

# Auto-fix issues (CRLF, remove nulls, remove _comment)
python scripts/validate_rules.py --fix rules.json

The script checks:

• Line endings (CRLF)
• No _comment fields
• No null values for optional fields
• Valid scope names
• Expression syntax warnings

About BPA rules

• BPA rules define automatic tests for semantic models in Power BI and Fabric for QA/QC
• BPA rules are used by Tabular Editor 2, 3, CLI, or Fabric notebooks
• Rule expressions are defined in C# for Tabular Editor or Python for Fabric Notebooks
• BPA rules are better defined and used by Tabular Editor because they are actionable with ability to ignore or fix, and they are integrated with the IDE

File Locations

BPA rules can exist in multiple locations (evaluated in order of priority):

Built-in Rules (TE3 Only)

Tabular Editor 3 includes built-in BPA rules embedded in the application. These are not stored as separate JSON files but are compiled into the DLLs.

Configuration: %LocalAppData%\TabularEditor3\Preferences.json

• BuiltInBpaRules: "Enable" | "Disable" | "EnableWithWarnings"
• DisabledBuiltInRuleIds: Array of rule IDs to disable

Built-in Rule IDs:

Note: This list is extracted from TE3 v3.25.0 Preferences.json. Built-in rules are not documented separately by Tabular Editor.

Model-embedded rules can be stored in two formats:

File format: All locations use the same JSON array format containing rule objects.

Priority: When the same rule ID exists in multiple locations, rules are merged with local rules taking precedence over remote/built-in rules.

Cross-Platform Access (macOS/Linux)

When working on macOS or Linux with Tabular Editor installed in a Windows VM:

Parallels on macOS:

Copy/Users/<macUser>/Library/Parallels/Windows Disks/{VM-UUID}/[C] <DiskName>.hidden/

Full paths to BPA rules:

• User-level: <ParallelsRoot>/Users/<WinUser>/AppData/Local/TabularEditor3/BPARules.json
• Machine-level: <ParallelsRoot>/ProgramData/TabularEditor3/BPARules.json

Other platforms:

• VMware Fusion - Check /Volumes/ for mounted Windows drives
• WSL on Windows - /mnt/c/Users/<username>/AppData/Local/TabularEditor3/

Note: The VM must be running for the filesystem to be accessible. If paths appear empty, start the Windows VM first.

Quick Reference

Rule JSON Structure

BPA rules have the following fields:

Copy{
  "ID": "RULE_PREFIX_NAME",
  "Name": "Human-readable rule name",
  "Category": "Performance|Formatting|Metadata|DAX Expressions|Naming Conventions|Governance",
  "Description": "Explanation of why this rule matters for %objecttype% '%objectname%'",
  "Severity": 2,
  "Scope": "Measure, CalculatedColumn, Table",
  "Expression": "DynamicLINQ expression returning true for violations",
  "FixExpression": "PropertyName = Value",
  "CompatibilityLevel": 1200
}

Valid Scope Values

All valid scope values from the RuleScope enum (can be combined with commas):

Backwards compatibility: Column expands to DataColumn, CalculatedColumn, CalculatedTableColumn; DataSource expands to ProviderDataSource

Severity Levels

Compatibility Levels

The CompatibilityLevel field specifies the minimum model version required. Rules only apply if the model's compatibility level >= the rule's level.

Note: Power BI models use 1560+ with current level at 1702. Use Model.Database.CompatibilityLevel in expressions to check the model's level.

Category Prefixes

Common ID prefix conventions:

Expression Syntax Overview

BPA expressions use Dynamic LINQ with access to TOM (Tabular Object Model) properties.

Basic Patterns

Copy// String checks
string.IsNullOrWhitespace(Description)
Name.StartsWith("_")
Expression.Contains("CALCULATE")

// Boolean checks
IsHidden
not IsHidden
IsVisible and not HasAnnotations

// Numeric checks
ReferencedBy.Count = 0
Columns.Count > 100

// Collection checks
DependsOn.Any()
Columns.All(IsHidden)

Common Properties by Scope

Measure:

• Expression, FormatString, DisplayFolder, Description
• IsHidden, IsVisible, ReferencedBy, DependsOn

Column:

• DataType, SourceColumn, FormatString, SummarizeBy
• IsHidden, IsKey, IsNullable, SortByColumn

Table:

• Columns, Measures, Partitions, IsHidden
• CalculationGroup (for calc group tables)

For complete expression syntax, see references/expression-syntax.md.

TMDL Annotations

BPA rules can be embedded in TMDL files via annotations:

Copyannotation BestPracticeAnalyzer = [{ "ID": "...", ... }]
annotation BestPracticeAnalyzer_IgnoreRules = {"RuleIDs":["RULE1","RULE2"]}
annotation BestPracticeAnalyzer_ExternalRuleFiles = ["https://..."]

For complete annotation patterns, see references/tmdl-annotations.md.

Workflow

Creating a New Rule

1. Identify the best practice to enforce
2. Determine the appropriate Scope
3. Write the Expression to detect violations
4. Optionally write a FixExpression for auto-remediation
5. Test against sample models
6. Add to rule collection

Improving an Existing Rule

1. Understand the current rule's intent
2. Identify false positives or missed cases
3. Refine the Expression logic
4. Verify FixExpression doesn't cause side effects
5. Test thoroughly

Additional Resources

Reference Files

For detailed syntax and patterns, consult:

• schema/bparules-schema.json - JSON Schema for validating BPA rule files (Draft-07) (temporary location)
• references/rule-schema.md - Human-readable BPA rule field descriptions
• references/expression-syntax.md - Dynamic LINQ expression syntax, TOM properties, Tokenize(), DependsOn, ReferencedBy
• references/tmdl-annotations.md - BPA annotations in TMDL format

Example Files

Working examples in examples/:

• examples/comprehensive-rules.json - 30+ production-ready rules across all categories
• examples/model-with-bpa-annotations.tmdl - TMDL file showing all annotation patterns

Scripts

Utility scripts:

• /scripts/bpa_rules_audit.py - Comprehensive BPA rules audit across all sources (built-in, URL, model, user, machine). Supports Windows, WSL, and macOS with Parallels. Outputs ASCII report and JSON export.
• scripts/validate_rules.py - Validate BPA rule JSON files for schema compliance

Audit Script Usage:

Copy# Basic audit
python scripts/bpa_rules_audit.py /path/to/model

# Export to JSON
python scripts/bpa_rules_audit.py /path/to/model --json output.json

# Quiet mode (summary only)
python scripts/bpa_rules_audit.py /path/to/model --quiet

Related Commands

• /suggest-rule - Generate BPA rules from descriptions

Related Agents

• bpa-expression-helper - Debug and improve BPA expressions

External References

• Tabular Editor BPA Getting Started
• Tabular Editor BPA View
• BPA Sample Rule Expressions
• TabularEditor BPA Source Code
• BPA Rules Repository
• TabularEditor Docs Repository
• Power BI Semantic Model Checklist

Example Rules

Measure Without Description

Copy{
  "ID": "META_MEASURE_NO_DESCRIPTION",
  "Name": "Measure has no description",
  "Category": "Metadata",
  "Description": "All measures should have descriptions for documentation.",
  "Severity": 2,
  "Scope": "Measure",
  "Expression": "string.IsNullOrWhitespace(Description)"
}

Hidden Unused Column

Copy{
  "ID": "PERF_UNUSED_HIDDEN_COLUMN",
  "Name": "Remove hidden columns not used",
  "Category": "Performance",
  "Description": "Hidden columns with no references waste memory.",
  "Severity": 3,
  "Scope": "Column",
  "Expression": "IsHidden and ReferencedBy.Count = 0 and not UsedInRelationships.Any()",
  "FixExpression": "Delete()"
}