# Fabriciq Ontology Authoring Cli > Create and evolve Fabric IQ Ontology (preview) items from CLI — define entity types, properties (including timeseries), relationship types, and bind them to OneLake lakehouse tables (static + timeseries) or Eventhouse / KQL database tables (timeseries only). Uses the Fabric item-definition REST API (Create Item / Update Item Definition) with `InlineBase64` parts. Use to create a Fabric Ontology i… - **Type:** Skill - **Install:** `agentstack add skill-microsoft-skills-for-fabric-fabriciq-ontology-authoring-cli` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [microsoft](https://github.com/microsoft) - **Source:** https://github.com/microsoft/skills-for-fabric/tree/main/plugins/fabric-skills/skills/fabriciq-ontology-authoring-cli ## Install ```sh agentstack add skill-microsoft-skills-for-fabric-fabriciq-ontology-authoring-cli ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About > **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](https://github.com/microsoft) - **Source:** [microsoft/skills-for-fabric](https://github.com/microsoft/skills-for-fabric) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-microsoft-skills-for-fabric-fabriciq-ontology-authoring-cli - Seller: https://agentstack.voostack.com/s/microsoft - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.