agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/skills/power-bi/fabric-tmdl/SKILL.md

fabric-tmdl

Skill1 starsChanged 34 days agoMITView on GitHub

TMDL (Tabular Model Definition Language) authoring rules for Fabric and Power BI semantic models. Use when editing .tmdl files, adding measures or columns to a semantic model, defining relationships or calculation groups, working in a PBIP definition/ folder, configuring Direct Lake partitions, writing a model's AI instructions (Prep data for AI), calling the semantic model Definition API (getDefinition, updateDefinition), or debugging TMDL validation errors. Covers syntax (tabs not spaces, /// descriptions, single-quoting names), DAX measure patterns, row-level security roles, calendar groups, and common gotchas.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 3 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do NOT add lineageTag on new objects — it is auto-generated

    line 29
  2. Very specific:

    Not at sync or refresh: the first portal commit after an edit in the service adds one to every table, column, measure and expression at …

    line 30
  3. Distinctive:

    Place measures before columns in table definitions

    line 35
  4. Very specific:

    Never set dataType on measures — it is inferred from DAX

    line 37
  5. Very specific:

    Check a hand-authored definition/ offline before a sync with TOM's TmdlSerializer from the SqlServer module: syntax and references, not DAX …

    line 38
  6. Very specific:

    Always set formatString — Currency: $#,##0.00 | Percentage: 0.00% | Integer: #,##0 | Decimal: #,##0.00

    line 62
  7. Very specific:

    Use DIVIDE() instead of / for safe division

    line 63
  8. Very specific:

    Never: use IFERROR — causes performance degradation

    line 64
  9. Very specific:

    Use displayFolder to organize measures into logical groups

    line 66
  10. Very specific:

    Add /// descriptions to explain business logic

    line 67
  11. Distinctive:

    Create relationships BEFORE measures that depend on them

    line 80
  12. Very specific:

    Default: crossFilteringBehavior: oneDirection.

    line 81
  13. Distinctive:

    No composite keys — use a single surrogate integer key

    line 93
  14. Very specific:

    Use formatStringDefinition (not formatString) for calc items that override measure format

    line 109
  15. Very specific:

    Do NOT use INFO.ROLES() / INFO.ROLEMEMBERSHIPS() via DAX — unreliable.

    line 121
  16. Very specific:

    Do NOT add PBI_* annotations manually — they are Power BI internal metadata

    line 125
  17. Very specific:

    ALL partitions must use EntityPartitionSource — no M/Power Query

    line 164

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Two jobs have a reference of their own: read it before answering one.

The jobRead first
Write the model's AI instructions, or edit a culture file's linguisticMetadataai-instructions.md
Create, read or update the model's definition through the Fabric APIdefinition-api.md

TMDL Authoring Rules

Syntax Rules

  • TMDL uses tab indentation — every nesting level is exactly one tab (\t), NOT spaces. Spaces cause validation errors.
    • PowerShell: use `t
    • Bash: use $'\t' or literal tabs
  • Objects declared by type + name: table Customer, column ProductId, measure 'Total Sales'
  • Names with spaces or special chars (., =, :, ') must be in single quotes: column 'Order Date'
  • Descriptions use /// placed ABOVE the object — do NOT use the description property
  • // comments are NOT supported in TMDL
  • Do NOT add lineageTag on new objects — it is auto-generated
    • Not at sync or refresh: the first portal commit after an edit in the service adds one to every table, column, measure and expression at once, and annotation PBI_ProTooling to model.tmdl (observed once, 2026-10-07). Review that commit as the tags plus the edit, not drift.
  • Multi-line DAX must be enclosed in triple backticks (```)
  • Place measures before columns in table definitions
  • formatString is required on every measure
  • Never set dataType on measures — it is inferred from DAX
  • Check a hand-authored definition/ offline before a sync with TOM's TmdlSerializer from the SqlServer module: syntax and references, not DAX (references/REFERENCE.md — BIM ↔ TMDL Conversion)

Naming Conventions

  • Tables: business-friendly, no Fact/Dim prefixes. Plural for facts (Sales), singular for dimensions (Product)
  • Columns: readable with spaces (Order Date, Unit Price)
  • Measures: clear patterns (Total Sales, # Customers). Time intelligence: [measure], [measure (ly)], [measure (ytd)])

Column Rules

PropertyRule
dataTypeRequired. Use int64, decimal, string, dateTime, boolean. Avoid double
sourceColumnMust match partition source column name exactly
isHiddenSet for ID columns, foreign keys, system columns
summarizeBynone for non-aggregatable numerics (IDs, postal codes, year numbers)
isAvailableInMdxfalse for hidden columns not used in sort-by or hierarchies
sortByColumnFor text needing non-alphabetical sort (month names → month number)

Measure & DAX Rules

  • Always set formatString — Currency: $#,##0.00 | Percentage: 0.00% | Integer: #,##0 | Decimal: #,##0.00
  • Use DIVIDE() instead of / for safe division
  • Never use IFERROR — causes performance degradation
  • Prefix VAR names with _: VAR _totalSales = ...
  • Use displayFolder to organize measures into logical groups
  • Add /// descriptions to explain business logic
  • If a scripts/data/dax.sh wrapper is deployed in the repo (an internal local-cli template), run a new measure against the published model before writing it into TMDL: dax.sh -q 'DEFINE MEASURE … EVALUATE …' returns what a report would show, after relationships and filter context, and its values say which formatString fits. It reads the published model, so a change on disk not yet deployed is not in it. It is an accelerator that happens to be present, never a dependency.

Relationship Rules

  • fromColumn: = many-side (fact); toColumn: = one-side (dimension)
  • Create relationships BEFORE measures that depend on them
  • Default: crossFilteringBehavior: oneDirection; add bothDirections only when needed
  • Role-playing dimensions: duplicate the table by default — Date, Ship Date, Delivery Date, each with one active relationship. Microsoft recommends "defining active relationships whenever possible", which "means that role-playing dimension tables should be duplicated in your model"; the cost is model size, "rarely a concern" for dimensions. isActive: false + USERELATIONSHIP() is the conditional case — only when no visual needs two roles at once and you write the measures. In Direct Lake, confirm duplication is available first (see below).
  • Both sides must have matching dataType
  • Set isKey: true on dimension primary key columns
  • Hide foreign keys on fact tables (isHidden: true)
  • No composite keys — use a single surrogate integer key

Calculation Groups

table 'Time Intelligence'
	calculationGroup
		calculationItem Current = SELECTEDMEASURE()
		calculationItem YTD = CALCULATE(SELECTEDMEASURE(), DATESYTD('Date'[Date]))
	column 'Time Intelligence'
		dataType: string
	partition 'Partition_Time Intelligence' = calculationGroup
  • calculationGroup keyword has NO name — just the keyword indented under the table
  • Partition type must be = calculationGroup (not = m or = calculated)
  • Use formatStringDefinition (not formatString) for calc items that override measure format

Security Roles

role RegionalManager
	modelPermission: read
	tablePermission Sales = [Region] = "East"
  • modelPermission: required — use read or readRefresh
  • Assign users via Power BI REST API, not TMDL: POST .../datasets/{id}/users with roles array
  • Do NOT use INFO.ROLES() / INFO.ROLEMEMBERSHIPS() via DAX — unreliable. Use the REST API.

Annotations

  • Do NOT add PBI_* annotations manually — they are Power BI internal metadata
  • Custom annotations are fine for documentation/tooling
  • Syntax: blank line before the first annotation; blank line between annotations; same indent as peer properties
column 'Product Name'
	dataType: string
	sourceColumn: Product Name

	annotation MyTool_Owner = analytics-team

model.tmdl Required Properties

model.tmdl is the root of the definition/ folder alongside database.tmdl, expressions.tmdl, functions.tmdl, relationships.tmdl, roles/, perspectives/, cultures/, and tables/.

model Model
	culture: en-US
	defaultPowerBIDataSourceVersion: powerBI_V3
	discourageImplicitMeasures
	sourceQueryCulture: en-US
	dataAccessOptions
		legacyRedirects
		returnErrorValuesAsNull

defaultPowerBIDataSourceVersion: powerBI_V3 is required for Import-mode models — without it, Import from JSON supported for V3 models only.


Direct Lake Configuration

  • ALL partitions must use EntityPartitionSource — no M/Power Query
  • A named expression pointing to the Lakehouse/Warehouse must be defined before tables:

    expression DL_Lakehouse =
    		let
    			Source = AzureStorage.DataLake("https://onelake.dfs.fabric.microsoft.com/<WorkspaceId>/<LakehouseId>", [HierarchicalNavigation=true])
    		in
    			Source
  • Each table partition references the expression:

    partition Sales = entity
    	mode: directLake
    	source
    		entityName: Sales
    		schemaName: dbo
    		expressionSource: DL_Lakehouse
  • dataType: binary columns are NOT supported in Direct Lake
  • Columns map directly via sourceColumn — no transforms
  • A model new to a workspace answers no table until its first refresh. Learn says Direct Lake tables an XMLA tool creates start unprocessed, and queries on them fail on OneLake; one that arrived by Git sync did the same (observed 2026-10-07). Refresh it once; the error text is in fabric-rest-api's references/gotchas.md.
  • Adding the same source table twice is not supported in Power BI Desktop or web modeling — XMLA tools can, but Edit tables and refresh then error. So the role-playing fix above usually has to happen upstream: add the role table to the lakehouse and bind it. Calculated tables are preview on Direct Lake on OneLake and unsupported on Direct Lake on SQL; Direct Lake calculated columns are unmaterialized and so can't be used in relationships.
  • Desktop and web modelling pick a Direct Lake relationship's many side by row count: "the table with more rows is considered as the many side", and nothing validates it (Edit tables). So a date table longer than its fact, as one spanning a planning horizon over a small fact is, comes out reversed, the date column in fromColumn (seen once in web modelling, 2026-09-30). Read relationships.tmdl back after creating one, since nothing errors: grouping by the reversed date table returned the fact's grand total on every year (DAX query view, 2026-09-30). The documented failure on a duplicate in a one-side column (limitations) presumably needs a query that filters across the relationship (untested).
  • Cross-environment rebinding (deployment pipelines): Direct Lake on OneLake does not support data source rules — the dropdowns are simply greyed out. Only the Direct Lake overview limitations table says so; the create-rules page doesn't. Instead, declare the workspace/lakehouse GUIDs as IsParameterQuery Text expressions and build the URL from them — concatenation works (AzureStorage.DataLake("https://onelake.dfs.fabric.microsoft.com/" & WorkspaceId & "/" & LakehouseId, ...)) — then rebind each target stage with parameter rules (verified live 2026-08-24).

Gotchas

IssueCauseFix
InvalidLineType: Property! in database.tmdlBare compatibilityLevel: without database declarationStart the file with database <Name> on line 1
Import from JSON supported for V3 models onlyMissing defaultPowerBIDataSourceVersionAdd powerBI_V3 to model.tmdl
Spaces-for-tabs validation errorsEditor converted tabsForce literal tabs; configure editor not to expand
// comment ignored or invalidNot supportedUse /// on line above the object (descriptions only)
Measure has wrong inferred typedataType was set manuallyRemove dataType from measures — always inferred
Missing formatString errorsMeasure without formatStringAlways set per measure; use formatStringDefinition for dynamic
Calc item format ignoredUsed formatString instead of formatStringDefinitionformatStringDefinition is DAX-based; only it overrides the selected measure's format
Broken report binding after column renameStale lineageTag left in placeNever edit lineageTag; let Power BI regenerate only on creation
Role members ignoredAuthored member staticallyAssign via Power BI REST API (POST datasets/{id}/users)
INFO.ROLES() returns stale/missing dataKnown DAX surface unreliabilityQuery membership via REST API
Calendar name collisionName unique per-table but not per-modelCalendar names must be globally unique across the model
Direct Lake partition errorsbinary column in sourceCast away in upstream Lakehouse/Warehouse; drop the column
...transformations that can't be used for DirectQuery refreshing a parameterized Direct Lake modelModel-page ribbon schema-and-data refresh re-evaluates the M; fires on any parameterized source shapeFalse alarm — data-only, workspace-page, scheduled, and pipeline refreshes just reframe and work (observed 2026-08-24, undocumented)
Perspective appears empty in Power BINo perspectiveTable childrenAdd at least one table + column/measure, or includeAll on a table
model.bim and definition/ both presentForgot to delete .bim after TMDL conversionRemove model.bim; they are mutually exclusive
TMDL conversion failsOld Microsoft.AnalysisServices.retail.amd64Upgrade NuGet package for TmdlSerializer
Hierarchy level references missing columnColumn removed or renamed without updating levellevel.column: must reference an existing same-table column
PBI_* annotation edits revertPower BI rewrites on saveDo not hand-author PBI internal annotations

Additional reference

  • Microsoft Learn: TMDL language overview
  • Microsoft Learn: TMDL view in Power BI Desktop
  • Microsoft Learn: Power BI Desktop project semantic model folder (PBIP)
  • Companion references/REFERENCE.md: per-object property tables (database, model, table, column, measure, relationship, hierarchy, partition, calculationGroup, role, perspective, cultureInfo, expression, function, dataSource, refreshPolicy, calendar, queryGroup), BIM ↔ TMDL conversion procedure, enum value lists, and a comprehensive MS Learn link bundle (TMDL syntax / TMDL view / PBIP folder / calculation groups / Direct Lake / DAX / TMSL / TOM).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.