Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the

  check-updates

  skill.
• Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version.
• Skip if the check was already performed earlier in this session.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

az

az rest

az login

jq

az rest

base64

[Convert]::ToBase64String

Agent check — verify before first operation:

bash

az version 2>/dev/null || echo "INSTALL: https://learn.microsoft.com/cli/azure/install-azure-cli"

• Read the relevant TMDL reference sections BEFORE generating any TMDL — at minimum read TMDL Syntax Rules and Modeling Best Practices. If the task involves relationships, hierarchies, calculation groups, security roles, or translations, also read the corresponding sections in tmdl-authoring-guide.md and tmdl-advanced-features-guide.md. Do not generate TMDL from memory.
• Always pass

  --resource

  to

  az rest

  — omitting it causes silent auth failures. Use the correct audience per the table above.
• Always pass

  --headers "Content-Type=application/json"

  on POST/PATCH/PUT calls with a

  --body

  to the Power BI Datasets API — omitting it causes

  Unsupported Media Type

  errors.
• Include ALL definition parts in

  updateDefinition

  — modified + 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.
• Poll LRO to completion —

  createItemWithDefinition

  ,

  getDefinition

  , and

  updateDefinition

  return

  202 Accepted

  with an

  Operation-Id

  header. Poll until terminal state.
• Base64-encode TMDL content — all

  payload

  values in definition parts must be base64-encoded.
• Single-quote names with special chars — names containing spaces,

  .

  ,

  =

  ,

  :

  , or

  '

  must be wrapped in single quotes in TMDL.
• Verify workspace has capacity before creating a semantic model — call

  GET /v1/workspaces/{id}

  and check

  capacityId

  .

• createItemWithDefinition

  (single POST) over create-then-update for new semantic models.
• TMDL format over TMSL — TMDL is text-based, diff-friendly, and the preferred format for Fabric.
• Measures before columns in TMDL table files — follows TMDL convention.
• Multi-line DAX in triple backticks — improves readability for complex expressions.
• Route fine-grained changes to

  powerbi-modeling-mcp

  — for adding/modifying individual measures, columns, or relationships, the MCP server is more efficient than full definition round-trips.
• Get definition before updating — always retrieve the current definition, modify, then POST back to avoid overwriting concurrent changes.
• Cross-reference

  powerbi-consumption-cli

  for post-creation validation — run DAX queries to verify measures, relationships, and data.

• updateDefinition

  for small changes — a full definition round-trip is heavy; route to

  powerbi-modeling-mcp

  for individual object edits.
• Report creation — not supported by this skill. Reports require a separate definition format (PBIR/PBIR-Legacy).

• lineageTag

  on new objects — TMDL auto-generates lineage tags; adding them manually causes conflicts.

• //

  comments in TMDL — not supported. Use

  ///

  descriptions instead.

• description

  property in TMDL — use

  ///

  syntax above the object instead.
• Hardcoded workspace/item IDs — resolve dynamically via REST API (see COMMON-CLI.md § Finding Workspaces and Items in Fabric).
• Sending only modified parts in

  updateDefinition

  — the API replaces the full definition; missing parts are deleted.

createItemWithDefinition

updateDefinition

definition.pbism

definition/database.tmdl

definition/model.tmdl

definition/tables/<TableName>.tmdl

Critical:

updateDefinition

must include ALL parts — modified and unmodified. The API replaces the entire definition. Never include

.platform

in update payloads.

model Model
	culture: en-US
	defaultPowerBIDataSourceVersion: powerBI_V3
	discourageImplicitMeasures

Note:

defaultPowerBIDataSourceVersion: powerBI_V3

is required for Import-mode models. Without it, the API returns

Import from JSON supported for V3 models only

.

Critical rules: Must include ALL parts (modified + unmodified). Never include

.platform

. The API replaces the entire definition — omitted parts are deleted.

WS_ID="<workspaceId>"
MODEL_ID="<semanticModelId>"

1. powerbi-modeling-mcp

   available → use MCP tools for fine-grained object changes (measures, columns, relationships)
2. MCP unavailable, TMDL files available → edit TMDL files directly, deploy via

   az rest

   updateDefinition
3. MCP unavailable, workspace only → use this skill: getDefinition → edit TMDL → updateDefinition

1. Discover workspace → list workspaces, find target by name (see COMMON-CLI.md § Finding Workspaces and Items)
2. List semantic models →

   GET /v1/workspaces/{id}/semanticModels

   to find existing models or confirm name availability
3. Analyze source schema → inspect source tables/columns via SQL, DAX, or Lakehouse metadata to inform star schema design
4. Design star schema → identify fact and dimension tables, define relationship keys, plan measures
5. Author TMDL files → create

   definition.pbism

   ,

   database.tmdl

   ,

   model.tmdl

   , and table files per Minimal TMDL Content Examples and tmdl-authoring-guide.md
6. Create relationships → define in table TMDL files before creating measures that depend on them
7. Create measures → add explicit measures with

   formatString

   for all aggregatable values
8. Deploy → base64-encode all parts → POST createItemWithDefinition (see Create Semantic Model)
9. Verify → run validation checks (see below)
10. Refresh → trigger dataset refresh via Refresh Operations
11. Validate with DAX → use powerbi-consumption-cli to run DAX queries against the deployed model

• TMDL structure — verify all required parts are present (definition.pbism, database.tmdl, model.tmdl, ≥1 table)
• Test measures — run

  EVALUATE { [Measure Name] }

  for each measure via DAX
• Verify relationships — confirm cardinality, cross-filter direction, matching

  dataType

  on both sides
• Verify columns — confirm

  sourceColumn

  mappings and

  dataType

  match source schema
• Check for duplicates — no duplicate measure names or orphan objects

Early-abort rule: If both

getDefinition

returns

404 EntityNotFound

(on an item you can list/GET) and the Power BI refresh API returns

403 Forbidden

with

"identity None"

, stop retrying immediately — the user almost certainly has only Viewer role on the workspace. Verify by calling

GET /v1/workspaces/{id}/roleAssignments

; if that also returns

403 InsufficientWorkspaceRole

, confirm to the user they need Contributor or higher role. Do not retry with different URL formats, endpoints, or parameters — the issue is permissions, not API usage.

403 Forbidden

"identity None"

404 EntityNotFound

403 InsufficientWorkspaceRole

401 Unauthorized

--resource

--resource "https://api.fabric.microsoft.com"

401 Unauthorized

--resource "https://analysis.windows.net/powerbi/api"

411 Length Required

--body '{}'

202 Accepted

Location

Succeeded

/result

.platform

.platform

.platform

?updateMetadata=true

base64 -w 0

[Convert]::ToBase64String()

lineageTag

lineageTag

lineageTag

INFO.ROLES()

INFO.ROLEMEMBERSHIPS()

INFO

GET /v1.0/myorg/groups/{workspaceId}/datasets/{datasetId}/users

roles