Fabriciq Ontology Authoring Cli

> 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 (e.g., /fabric-skills:check-updates). > - Claude Code / Cowork / Cursor / Windsurf / Codex: read the local package.json version, then compare against remote via git fetch origin main --quiet && git show origin/main:package.json (or the GitHub API). If remote is newer, show the changelog and update instructions. > - Skip if the check was already performed earlier in this session.

> CRITICAL NOTES > 1. Ontology is preview. The item type value is Ontology. Features and wire format may change; validate against the current docs before production use. > 2. To find the workspace details (including its ID) from workspace name: list all workspaces and use JMESPath filtering. > 3. To find the item details (including its ID) from workspace ID, item type (Ontology), and item name: list all items of that type in that workspace and use JMESPath filtering. > 4. Authoring a relationship type requires two distinct entity types that already exist in the ontology. The source.entityTypeId and target.entityTypeId values are the entity type IDs you assigned, not item IDs. > 5. Data bindings reference a source table by workspaceId, itemId, sourceTableName, and — for lakehouse sources — sourceSchema. Lakehouse (LakehouseTable) sources carry the lakehouse item ID; Eventhouse (KustoTable) sources carry the Eventhouse item ID plus clusterUri and databaseName. Key column(s) on the source side must match the entity type's key property(ies). Eventhouse sources are TimeSeries-only; the static (NonTimeSeries) binding must come from a lakehouse.

fabriciq-ontology-authoring-cli — Fabric Ontology Authoring via CLI

Table of Contents

| Task | Reference | Notes | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | Finding Workspaces and Items in Fabric | [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) | Mandatory — resolve workspace/item IDs before authoring | | Fabric Topology & Key Concepts | [COMMON-CORE.md § Fabric Topology & Key Concepts](../../common/COMMON-CORE.md#fabric-topology--key-concepts) | Workspace → Item hierarchy | | Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) | Use https://api.fabric.microsoft.com audience for control plane | | Core Control-Plane REST APIs | [COMMON-CORE.md § Core Control-Plane REST APIs](../../common/COMMON-CORE.md#core-control-plane-rest-apis) | Create Item, Get/Update Item Definition | | Long-Running Operations (LRO) | [COMMON-CORE.md § Long-Running Operations (LRO)](../../common/COMMON-CORE.md#long-running-operations-lro) | Item create/update returns an LRO | | Rate Limiting & Throttling | [COMMON-CORE.md § Rate Limiting & Throttling](../../common/COMMON-CORE.md#rate-limiting--throttling) | | | Authentication Recipes | [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes) | az login; token acquisition | | Fabric Control-Plane API via az rest | [COMMON-CLI.md § Fabric Control-Plane API via az rest](../../common/COMMON-CLI.md#fabric-control-plane-api-via-az-rest) | Always pass --resource https://api.fabric.microsoft.com | | Long-Running Operations (LRO) Pattern | [COMMON-CLI.md § Long-Running Operations (LRO) Pattern](../../common/COMMON-CLI.md#long-running-operations-lro-pattern) | For Ontology create/update, poll /v1/operations/{x-ms-operation-id} on the Fabric host — see [LRO Header Capture](#lro-header-capture-with-az-rest) | | Gotchas & Troubleshooting (CLI-Specific) | [COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific)](../../common/COMMON-CLI.md#gotchas--troubleshooting-cli-specific) | Token audience, shell escaping | | az rest Template | [COMMON-CLI.md § az rest Template](../../common/COMMON-CLI.md#az-rest-template) | | | Definition Envelope (parts, payloadType) | [ITEM-DEFINITIONS-CORE.md § Definition Envelope](../../common/ITEM-DEFINITIONS-CORE.md#definition-envelope) | InlineBase64 parts pattern used for Ontology | | Ontology Definition Reference | [ONTOLOGY-AUTHORING-CORE.md § Definition Tree](references/ONTOLOGY-AUTHORING-CORE.md#definition-tree) | Authoritative file/folder layout for the ontology item | | EntityType & EntityTypeProperty schema | [ONTOLOGY-AUTHORING-CORE.md § EntityType file](references/ONTOLOGY-AUTHORING-CORE.md#entitytype-file--entitytypesiddefinitionjson) | Allowed valueType values, key constraints, name regex | | DataBinding schema + source-type mapping | [ONTOLOGY-AUTHORING-CORE.md § DataBinding file](references/ONTOLOGY-AUTHORING-CORE.md#databinding-file--entitytypesiddatabindingsguidjson) | Lakehouse & Eventhouse shapes; value-type mapping; binding rules | | RelationshipType + Contextualization schema | [ONTOLOGY-AUTHORING-CORE.md § RelationshipType file](references/ONTOLOGY-AUTHORING-CORE.md#relationshiptype-file--relationshiptypesiddefinitionjson) | Source/target constraints, link table requirements | | Ontology Concepts | [SKILL.md § Ontology Item Concepts](#ontology-item-concepts) | Entity types, properties, bindings, relationship types | | Tool Stack | [SKILL.md § Tool Stack](#tool-stack) | | | Connection | [SKILL.md § Connection](#connection) | Discover workspace, lakehouse, ontology IDs | | Authoring Scope | [SKILL.md § Authoring Scope](#authoring-scope) | Supported operations at a glance | | Authoring Mechanics (full reference) | [authoring-mechanics.md](references/authoring-mechanics.md) | Envelope, IDs, create, entity types, bindings, relationships, update, verify | | Worked Examples | [examples.md](references/examples.md) | End-to-end bash recipes (create → bind → relationship → timeseries) | | Preview & Confirm (mandatory before LRO write) | [preview-and-confirm.md](references/preview-and-confirm.md) | ASCII proposal (greenfield) / change-set diff (brownfield) | | Script Templates | [definition-script-templates.md](references/definition-script-templates.md) | Bash / PowerShell fetch-mutate-send scaffolds | | Must / Prefer / Avoid / Troubleshooting | [SKILL.md § Must / Prefer / Avoid / Troubleshooting](#must--prefer--avoid--troubleshooting) | LLM decision rules | | Agentic Workflows | [SKILL.md § Agentic Workflows](#agentic-workflows) | Exploration-before-authoring, script generation | | Agent Integration Notes | [SKILL.md § Agent Integration Notes](#agent-integration-notes) | How this skill composes with agents / other skills |

---

Ontology Item Concepts

A Fabric Ontology item is authored as a tree of JSON files inside the item definition. Each file is carried as a part in the parts[] array of the Create/Update definition envelope (payloadType InlineBase64).

| Concept | Definition file path | Purpose | |---|---|---| | Ontology envelope | definition.json | Empty {}; required | | Platform metadata | .platform | { "metadata": { "type": "Ontology", "displayName": "" } } | | Entity type | EntityTypes/{entityTypeId}/definition.json | Name, namespace, key(s), display name property, properties[], timeseriesProperties[] | | Entity type data binding | EntityTypes/{entityTypeId}/DataBindings/{guid}.json | Maps a lakehouse or eventhouse table to properties; dataBindingType = NonTimeSeries or TimeSeries. Eventhouse (KustoTable) sources are allowed only for TimeSeries | | Entity type documents | EntityTypes/{entityTypeId}/Documents/{name}.json | Optional doc links | | Entity type overviews | EntityTypes/{entityTypeId}/Overviews/definition.json | Optional widgets layout | | Entity type resource links | EntityTypes/{entityTypeId}/ResourceLinks/definition.json | Optional Power BI / item links | | Relationship type | RelationshipTypes/{relTypeId}/definition.json | Source + target entity type IDs, name | | Relationship contextualization | RelationshipTypes/{relTypeId}/Contextualizations/{guid}.json | Source/target key bindings onto a lakehouse table |

Property valueType allowed values (exact): String, Boolean, DateTime, Object, BigInt, Double. Use BigInt — not Int64 — for integers; there is no Guid value type (model GUIDs as String). Timeseries bindings require a timestamp column (source type datetime / date / timestamp) and a TimeSeries binding with timestampColumnName. See [ONTOLOGY-AUTHORING-CORE.md § EntityTypeProperty](references/ONTOLOGY-AUTHORING-CORE.md#entitytypeproperty) for the full source-column → valueType mapping.

> ⚠️ Property names must be unique across both properties[] and timeseriesProperties[] within a single entity type. If a lakehouse table and an Eventhouse table both contain a column with the same name (e.g., tenant_id), you must rename one of the ontology property names to avoid a collision. The sourceColumnName in the binding can still point to the original column — only the ontology property name must be unique. For example, keep the static property as TenantId and name the timeseries one TsTenantId. > > ⚠️ Property names with the same name across different entity types must share the same valueType — the ontology enforces name-level type consistency across the entire definition. If SerialNum is String on one entity type, it cannot be BigInt on another. Either use the same valueType everywhere, or disambiguate with a prefix (e.g., SerialNumStr vs SerialNumInt). > > ⚠️ Part paths must always use forward slashes (EntityTypes/{id}/definition.json), never backslashes. On Windows, PowerShell path-joining operators (Join-Path, \) produce backslashes that the Fabric API rejects with ALMOperationBadRequest. Always build part paths with string interpolation using /.

---

Tool Stack

Ontology authoring uses the same Fabric control-plane tool stack as every other CLI skill — see [COMMON-CLI.md § Tool Selection Rationale](../../common/COMMON-CLI.md#tool-selection-rationale) for the canonical list (install commands, prerequisite checks, base64 helpers, JSON tooling) and [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes) for az login + token acquisition.

Ontology-specific tool guidance below covers only the gotchas that hit createItem / updateDefinition payloads.

> ⚠️ PowerShell ConvertTo-Json Warning: PowerShell's ConvertTo-Json can silently reorder keys and serialize $null differently than JSON null, which can cause ALMOperationImportFailed errors on updateDefinition. To avoid this: > > 1. Always use [System.IO.File]::WriteAllText with [System.Text.UTF8Encoding]::new($false) to write JSON files — Out-File and Set-Content add a BOM that corrupts the payload. > 2. Build JSON with jq instead of ConvertTo-Json where possible — jq -nc produces deterministic, compact JSON without PowerShell serialization quirks: > ``powershell > $json = '{}' | jq -nc --arg id "$ET_ID" --arg name "Site" '{id:$id,name:$name}' > ` > 3. **Validate** the JSON before sending: Get-Content envelope.json | jq . — if jq fails, the payload is malformed. > 4. **Use -Depth 10** on ConvertTo-Json` — the default depth of 2 silently truncates nested objects.

> ⚠️ Avoid certutil -encode for InlineBase64 parts. Its output is line-wrapped with a header/footer and must be post-processed before use. On Windows, use PowerShell's [Convert]::ToBase64String([IO.File]::ReadAllBytes($path)) instead.

---

Connection

Ontology authoring targets the Fabric control plane. Before composing the definition you need: WS_ID (workspace), LH_ID (lakehouse item ID for static + lakehouse-timeseries bindings), and — for Eventhouse-backed timeseries — the Eventhouse item ID, KQL cluster URI, and KQL database name.

• Sign in + acquire the Fabric control-plane token → [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes) (always --resource https://api.fabric.microsoft.com).
• Resolve workspace, folder, lakehouse, and ontology item IDs by displayName → [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) (covers pagination + JMESPath filtering).
• Generic az rest invocation template → [COMMON-CLI.md § Fabric Co

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills-for-fabric
• License: MIT

Install and usage instructions live in the source repository linked above.