Fabric Tmdl

TMDL Authoring Rules

Syntax Rules (MUST follow)

• 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
• 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

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

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

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

• 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.

• 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

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).