Support for TMDL

pbi-tools supports TMDL, the new Tabular Model Definition Language (released in 2023), a strategic investment into code-first, collaborative, model development for Power BI, fully aligned with the pbi-tools vision.

Introduction to TMDL (Tabular Model Definition Language)

TMDL is a new declarative language for tabular models, released by Microsoft in April 2023. It is the successor to TMSL (Tabular Model Scripting Language) and was designed from the ground up to address developer needs.

The TMDL format is:

Human-Readable
Editable in any text editor
Suitable for collaborative development

Learn more about TMDL at Microsoft’s official documentation.

Since TMDL is available as part of the public TOM Nuget packages, external tools like Tabular Editor and pbi-tools can fully support the new format.

Using TMDL with pbi-tools

Starting with the 1.0.0-rc.3 Release, pbi-tools has had support for TMDL.

Specifially, the extract, convert, compile, and deploy actions are TMDL-aware.

Both, extract and convert, support the -modelSerialization command-line argument to determine the serialization format for the model part of a project. (See the table below for a description of all possible options.)

Each extract/serialization process will determine the effective model format from the first applicable option below (in the order given):

CLI -modelSerialization argument
The settings.model.serializationMode property in the project’s .pbixproj.json.
The PBITOOLS_DefaultModelSerialization environment variable.
The ModelSerialization.Default setting, which (currently) maps to Tmdl.

Any operations consuming project files, compile, and deploy specifically, are able to read model sources in any supported format (TMDL, PbixProj = Legacy, model.bim), without any further hints required.

Note: Tabular Editor’s proprietary "Save to Folder" format is not supported. For interoperability with Tabular Editor use either model.bim or the TMDL format.

TMDL is still in public preview. So far, ten preview releases were published. Follow this GitHub repository to keep track of the latest release and any noteable changes. Whilst some breaking changes occurred between earlier previews, the TMDL format can now be considered fairly stable. For maximum interoperability between Power BI and external tools it is strongly recommended to always upgrade to the latest tool updates. The repository mentioned above references matching external tool versions.

The pbi-tools sample repository has been upgraded to the TMDL format (see the pbix/Model folder).

ModelSerialization Options

Settings	Description
`Default`	The default serialization format, effective if no option is specified. The default is (currently) TMDL. Note that the meaning of “Default” could potentially (although unlikely) change in the future. Explicitly specify “Tmdl” if you always want TMDL output.
`Tmdl`	Serializes the tabular model into TMDL format. Annotation settings (`settings.model.annotations`) are applied and the `settings.model.format` options are honored (see 1.0.0-rc.8 Release).
`Raw`	Serializes the tabular model into a single JSON file (“model.bim”) containing the full TMSL payload from the PBIX model. No transformations are applied.
`Legacy`	Serializes the tabular model into the proprietary PbixProj folder structure and performs various transformations to optimize file contents for source control.

Extract PBIX file with model.bim output (instead of default TMDL)

Use this for max interoperability.

pbi-tools {filepath.pbix} -modelSerialization Raw

Convert a model file or folder (model.bim, PbixProj) to TMDL format

pbi-tools convert ./Model -overwrite

Convert a model folder (TMDL, PbixProj) to BIM file