Fabric Tmdl API

Semantic Model Definition API rules

• Two audiences: Fabric API (api.fabric.microsoft.com) for CRUD on definitions; Power BI API (analysis.windows.net/powerbi/api) for refresh, data sources, permissions
• updateDefinition must include ALL parts — modified AND unmodified. The API replaces the entire definition; omitting parts deletes them.
• Never include .platform in updateDefinition payloads — it is Git integration metadata and causes errors
• Base64-encode all TMDL content in definition payloads
• getDefinition is a POST (not GET) — requires --body '{}'
• Poll LRO to completion — createItemWithDefinition, getDefinition, and updateDefinition return 202

Required TMDL Parts

Critical: database.tmdl MUST start with database object declaration, not bare properties. Bare compatibilityLevel: causes InvalidLineType: Property! errors.

model.tmdl Required Properties

model Model
 culture: en-US
 defaultPowerBIDataSourceVersion: powerBI_V3
 discourageImplicitMeasures

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

• Calculated columns / tables (April 2026 preview): Direct Lake on OneLake now supports unmaterialized calculated columns (and calculated tables that reference them). Direct Lake on SQL still does not. User-context-aware DAX (USERCULTURE, USERPRINCIPALNAME, CUSTOMDATA, etc.) requires expressionContext: userContext on the column. Authorable in Power BI Desktop and web modeling, without changing storage mode. See fabric-tmdl REFERENCE for the storage-mode × Expression-Context support matrix.

Reference

• Microsoft Learn: Item definition overview (Fabric REST)
• Microsoft Learn: SemanticModel definition envelope
• Microsoft Learn: Develop Direct Lake semantic models (TMDL partition mode)
• Comprehensive MS Learn link bundle (definition envelope / REST CRUD / TMDL language / required parts / Direct Lake configuration / refresh APIs): references/REFERENCE.md

See also

• fabric-rest-api skill — LRO polling pattern, runtime item ID vs logicalId
• fabric-auth skill — Fabric vs Power BI audience selection
• fabric-cli skill — fab export / fab import wrap these APIs