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.
In this repository38 other files it gives its agents.
- claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- author-skillSkill
- drift-auditSkill
- drift-handoffSkill
- drift-updateSkill
- test-skillSkill
- triageSkill
- fabric-iqSkill
- fabric-catalog-governanceSkill
- fabric-deploySkill
- fabric-rest-apiSkill
- fabric-securitySkill
- fabric-variable-librarySkill
- fabric-databaseSkill
- fabric-dataflowSkill
- fabric-data-pipelineSkill
- fabric-sparkSkill
- fabric-warehouse-monitoringSkill
- fabric-warehouseSkill
- fabric-activatorSkill
- fabric-eventhouseSkill
- fabric-event-schema-setSkill
- fabric-eventstreamSkill
- fabric-realtime-dashboardSkill
- learnSkill
- fabric-semantic-model-auditSkill
- pbip-project-structureSkill
- pbir-report-workflowSkill
- linkedin-highlightsSkill
- msix-packagingSkill
- code-reviewSkill
- commitSkill
- find-sessionSkill
- landSkill
- prune-branchesSkill
- recreate-repoSkill
- run-briefsSkill
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
- Very specific: line 29
Do NOT add lineageTag on new objects — it is auto-generated
- Very specific: line 30
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 …
- Distinctive: line 35
Place measures before columns in table definitions
- Very specific: line 37
Never set dataType on measures — it is inferred from DAX
- Very specific: line 38
Check a hand-authored definition/ offline before a sync with TOM's TmdlSerializer from the SqlServer module: syntax and references, not DAX …
- Very specific: line 62
Always set formatString — Currency: $#,##0.00 | Percentage: 0.00% | Integer: #,##0 | Decimal: #,##0.00
- Very specific: line 63
Use DIVIDE() instead of / for safe division
- Very specific: line 64
Never: use IFERROR — causes performance degradation
- Very specific: line 66
Use displayFolder to organize measures into logical groups
- Very specific: line 67
Add /// descriptions to explain business logic
- Distinctive: line 80
Create relationships BEFORE measures that depend on them
- Very specific: line 81
Default: crossFilteringBehavior: oneDirection.
- Distinctive: line 93
No composite keys — use a single surrogate integer key
- Very specific: line 109
Use formatStringDefinition (not formatString) for calc items that override measure format
- Very specific: line 121
Do NOT use INFO.ROLES() / INFO.ROLEMEMBERSHIPS() via DAX — unreliable.
- Very specific: line 125
Do NOT add PBI_* annotations manually — they are Power BI internal metadata
- Very specific: line 164
ALL partitions must use EntityPartitionSource — no M/Power Query
≈ “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.
Files
Two jobs have a reference of their own: read it before answering one.
| The job | Read first |
Write the model's AI instructions, or edit a culture file's linguisticMetadata | ai-instructions.md |
| Create, read or update the model's definition through the Fabric API | definition-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
- PowerShell: use
- 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 thedescriptionproperty //comments are NOT supported in TMDL- Do NOT add
lineageTagon 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_ProToolingtomodel.tmdl(observed once, 2026-10-07). Review that commit as the tags plus the edit, not drift.
- 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
- Multi-line DAX must be enclosed in triple backticks (
```) - Place measures before columns in table definitions
formatStringis required on every measure- Never set
dataTypeon measures — it is inferred from DAX - Check a hand-authored
definition/offline before a sync with TOM'sTmdlSerializerfrom theSqlServermodule: syntax and references, not DAX (references/REFERENCE.md — BIM ↔ TMDL Conversion)
Naming Conventions
- Tables: business-friendly, no
Fact/Dimprefixes. 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
| Property | Rule |
dataType | Required. Use int64, decimal, string, dateTime, boolean. Avoid double |
sourceColumn | Must match partition source column name exactly |
isHidden | Set for ID columns, foreign keys, system columns |
summarizeBy | none for non-aggregatable numerics (IDs, postal codes, year numbers) |
isAvailableInMdx | false for hidden columns not used in sort-by or hierarchies |
sortByColumn | For 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
VARnames with_:VAR _totalSales = ... - Use
displayFolderto organize measures into logical groups - Add
///descriptions to explain business logic - If a
scripts/data/dax.shwrapper 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 whichformatStringfits. 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; addbothDirectionsonly 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: trueon 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' = calculationGroupcalculationGroupkeyword has NO name — just the keyword indented under the table- Partition type must be
= calculationGroup(not= mor= calculated) - Use
formatStringDefinition(notformatString) for calc items that override measure format
Security Roles
role RegionalManager
modelPermission: read
tablePermission Sales = [Region] = "East"modelPermission:required — usereadorreadRefresh- Assign users via Power BI REST API, not TMDL:
POST .../datasets/{id}/userswithrolesarray - 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-teammodel.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
returnErrorValuesAsNulldefaultPowerBIDataSourceVersion: 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 SourceEach table partition references the expression:
partition Sales = entity mode: directLake source entityName: Sales schemaName: dbo expressionSource: DL_LakehousedataType: binarycolumns 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'sreferences/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). Readrelationships.tmdlback 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
IsParameterQueryText 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
| Issue | Cause | Fix |
InvalidLineType: Property! in database.tmdl | Bare compatibilityLevel: without database declaration | Start the file with database <Name> on line 1 |
Import from JSON supported for V3 models only | Missing defaultPowerBIDataSourceVersion | Add powerBI_V3 to model.tmdl |
| Spaces-for-tabs validation errors | Editor converted tabs | Force literal tabs; configure editor not to expand |
// comment ignored or invalid | Not supported | Use /// on line above the object (descriptions only) |
| Measure has wrong inferred type | dataType was set manually | Remove dataType from measures — always inferred |
Missing formatString errors | Measure without formatString | Always set per measure; use formatStringDefinition for dynamic |
| Calc item format ignored | Used formatString instead of formatStringDefinition | formatStringDefinition is DAX-based; only it overrides the selected measure's format |
| Broken report binding after column rename | Stale lineageTag left in place | Never edit lineageTag; let Power BI regenerate only on creation |
| Role members ignored | Authored member statically | Assign via Power BI REST API (POST datasets/{id}/users) |
INFO.ROLES() returns stale/missing data | Known DAX surface unreliability | Query membership via REST API |
| Calendar name collision | Name unique per-table but not per-model | Calendar names must be globally unique across the model |
| Direct Lake partition errors | binary column in source | Cast away in upstream Lakehouse/Warehouse; drop the column |
...transformations that can't be used for DirectQuery refreshing a parameterized Direct Lake model | Model-page ribbon schema-and-data refresh re-evaluates the M; fires on any parameterized source shape | False alarm — data-only, workspace-page, scheduled, and pipeline refreshes just reframe and work (observed 2026-08-24, undocumented) |
| Perspective appears empty in Power BI | No perspectiveTable children | Add at least one table + column/measure, or includeAll on a table |
model.bim and definition/ both present | Forgot to delete .bim after TMDL conversion | Remove model.bim; they are mutually exclusive |
| TMDL conversion fails | Old Microsoft.AnalysisServices.retail.amd64 | Upgrade NuGet package for TmdlSerializer |
| Hierarchy level references missing column | Column removed or renamed without updating level | level.column: must reference an existing same-table column |
PBI_* annotation edits revert | Power BI rewrites on save | Do 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).
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
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.

