Eventschemaset Consumption 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 it against the remote version via git fetch origin main --quiet && git show origin/main:package.json (or the GitHub API). If the remote version is newer, show the changelog and update instructions.

> - 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

> 3. Eventstream ≠ EventSchemaSet. Eventstream is a real-time event ingestion and routing pipeline. For operations concerning eventstreams, use eventstream-authoring-cli or eventstream-consumption-cli.

> 4. Eventhouse ≠ EventSchemaSet. An Eventhouse is a workspace item (container) that holds one or more KQL databases for storing and analyzing large volumes of streaming/event data. For KQL database operations, use eventhouse-authoring-cli or eventhouse-consumption-cli.

Event Schema Set Consumption — CLI Skill

> Preview: The Fabric EventSchemaSet item and its REST operations (List, Get, GetDefinition) are currently in Preview — behavior, response shapes, and availability may change.

>

> Identity (all operations): Microsoft Learn documents every Event Schema Set REST operation (List, Get, GetDefinition) as supporting delegated (user) identity only — with service principals and managed identities listed as not supported. In practice, because the item is in Preview, service-principal / managed-identity access can succeed and is tenant-dependent. Prefer signing in as a user with az login (not --service-principal, and not a managed-identity context). If you must use a service principal or managed identity and a call fails with 401/403, fall back to a delegated user identity.

Table of Contents

| Task | Reference | Notes |

|---|---|---|

| Finding Workspaces and Items in Fabric | COMMON-CLI.md § Finding Workspaces and Items in Fabric | Mandatory — *READ link first* [needed for finding workspace id by its name or item id by its name, item type, and workspace id] |

| Fabric Topology & Key Concepts | COMMON-CORE.md § Fabric Topology & Key Concepts | |

| Environment URLs | COMMON-CORE.md § Environment URLs | |

| Authentication & Token Acquisition | COMMON-CORE.md § Authentication & Token Acquisition | Wrong audience = 401; read before any auth issue |

| Core Control-Plane REST APIs | COMMON-CORE.md § Core Control-Plane REST APIs | Includes pagination, LRO polling, and rate-limiting patterns |

| Gotchas, Best Practices & Troubleshooting | COMMON-CORE.md § Gotchas, Best Practices & Troubleshooting | |

| Tool Selection Rationale | COMMON-CLI.md § Tool Selection Rationale | |

| Authentication Recipes | COMMON-CLI.md § Authentication Recipes | az login flows and token acquisition |

| Fabric Control-Plane API via az rest | COMMON-CLI.md § Fabric Control-Plane API via az rest | Always pass --resource; includes pagination and LRO helpers |

| Gotchas & Troubleshooting (CLI-Specific) | COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific) | az rest audience, shell escaping, token expiry |

| Quick Reference | COMMON-CLI.md § Quick Reference | az rest template + token audience/tool matrix |

| List Event Schema Sets | SKILL.md § List Event Schema Sets | |

| Get Event Schema Set (Properties) | SKILL.md § Get Event Schema Set (Properties) | |

| Get Event Schema Set Definition | SKILL.md § Get Event Schema Set Definition | Decode base64 definition → summarize eventTypes & schemas |

| Validate Event Schema Set Configuration | SKILL.md § Validate Event Schema Set Configuration | |

| Must / Prefer / Avoid | SKILL.md § Must / Prefer / Avoid | MUST DO / AVOID / PREFER checklists |

| Examples | SKILL.md § Examples | Prompt → command-flow pairs (list, inspect, decode definition, get schema version, list business events) |

| Agent Integration Notes | SKILL.md § Agent Integration Notes | |

Tool Stack

| Tool | Purpose |

|---|---|

| az cli | REST calls via az rest; Fabric control-plane discovery |

| jq | JSON processing and output formatting |

| curl | Required for fabric_lro when polling 202 Accepted long-running operations (captures the Location header) |

See COMMON-CLI.md for installation and authentication setup.

List Event Schema Sets

List All Event Schema Sets in a Workspace

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventSchemaSets" \
  --resource "https://api.fabric.microsoft.com"

Returns a JSON object with a value array of items. Use JMESPath to filter by the Event Schema Set's

display name (set ITEM_NAME to the name you are looking for — not the

eventSchemaSets collection segment from the URL):

ITEM_NAME="my-event-schema-set"
az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventSchemaSets" \
  --resource "https://api.fabric.microsoft.com" \
  --query "value[?displayName=='${ITEM_NAME}']"

Get Event Schema Set (Properties)

Return the properties of a single Event Schema Set with the

Get Event Schema Set

operation (read-only, scope Item.Read.All or Item.ReadWrite.All):

az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}" \
  --resource "https://api.fabric.microsoft.com"

The response returns the item metadata:

| Field | Description |

|---|---|

| id | Item ID (GUID) |

| displayName | Item display name |

| description | Item description |

| type | Always EventSchemaSet |

| workspaceId | Owning workspace ID |

| folderId | Folder ID (if the item is in a folder) |

| properties.oneLakeRootPath | OneLake path to the Event Schema Set root directory |

| sensitivityLabel.id | Applied sensitivity label ID (if any) |

| tags | List of applied tags (id, displayName) |

When reporting to the user, summarize the display name, description, properties.oneLakeRootPath, and

sensitivity label. To read the schema contents (eventTypes / schemas), use

Get Event Schema Set Definition below.

Get Event Schema Set Definition

Retrieve the full definition of a selected Event Schema Set with the

Get Event Schema Set Definition

operation. The definition contains a schema part (named EventSchemaSetDefinition.json per the

definition article; the API may return a versioned name such as EventSchemaSetV1.json) plus a

.platform metadata part. The schema part's payload is base64-encoded JSON describing the

item's eventTypes and schemas.

> Spec: EventSchemaSet definition

>

> Scope: getDefinition requires Item.ReadWrite.All (read + write workspace permissions),

> even though it only reads the definition. (List and Get require read permissions.)

>

> Identity: Microsoft Learn documents getDefinition (like List and Get) as supporting

> delegated (user) identity only, with service principals and managed identities not

> supported. In practice this is Preview behavior and service-principal / managed-identity

> access can succeed depending on the tenant (see the top-level Identity note). Prefer a

> delegated user; on 401/403 with an SP/MI, fall back to az login.

Step 1: Retrieve the Definition

getDefinition is a POST (not GET) on the Event Schema Set endpoint. It supports an optional

?format={format} query parameter. Always send an explicit empty JSON body (--body '{}') —

a POST without a body can return 411 Length Required.

The examples below assume the common synchronous 200 OK response, whose body is the

definition. getDefinition may instead return a 202 Accepted long-running operation with an

empty body — the definition is *not* in the 202 response, so piping it straight into jq

yields nothing. Handle the async path explicitly (see If getDefinition returns 202 Accepted below).

az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --body '{}'

Step 2: Decode the Definition Part

Extract the schema part (everything except .platform) and base64-decode its payload:

# Using jq + base64 (Linux; on macOS use base64 -D instead of -d)
az rest --method POST \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}/getDefinition" \
  --resource "https://api.fabric.microsoft.com" \
  --body '{}' \
  | jq -r '.definition.parts[] | select(.path != ".platform") | .payload' \
  | base64 -d | jq .

# PowerShell (Windows)
$def = az rest --method POST `
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WORKSPACE_ID/eventSchemaSets/$ITEM_ID/getDefinition" `
  --resource "https://api.fabric.microsoft.com" `
  --body '{}' | ConvertFrom-Json
$payload = ($def.definition.parts | Where-Object { $_.path -ne '.platform' }).payload
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($payload)) | ConvertFrom-Json | ConvertTo-Json -Depth 10

If getDefinition returns 202 Accepted (async)

az rest surfaces only the response body, not headers, so on a 202 the operation URL in

the Location header is not visible to az rest alone. This is the standard Fabric

long-running-operation (LRO) pattern: capture Location, poll until Succeeded (honouring

Retry-After), then GET the operation result and decode its parts as shown above. Use the

reusable fabric_lro helper — see COMMON-CLI.md § Long-Running Operations

— rather than hand-rolling token capture and the poll loop here.

On a synchronous 200 OK, skip this and decode the POST response directly as shown above.

Step 3: Summarize the Definition

The decoded schema part has two top-level collections (both optional):

| Field | Type | Description |

|---|---|---|

| eventTypes | EventType[] | Event metadata used to communicate between source, Eventstream, and destination items |

| schemas | Schema[] | Formats used to represent the messages stored in the catalog |

Each EventType exposes: id (required), description, eventTypeCategory

(EventType or BusinessEventType), format (required), envelopeMetadata, schemaUrl,

schemaFormat, schema, protocol, and protocolOptions. schemaUrl and schema are mutually

exclusive.

Each Schema exposes: id (required), description, format (required, e.g. JsonSchema),

and versions (the iterations of that schema).

When reporting to the user, enumerate the event types (id, category, format, and whether they carry

an inline schema or a schemaUrl) and the schemas (id, format, and version count).

Validate Event Schema Set Configuration

After decoding the definition (see Get Event Schema Set Definition),

use the parsed structure to answer read-only validation questions about how the Event Schema Set is

configured. This is inspection only — it never mutates the item.

• Inline schema vs schemaUrl per event type — schema (an embedded schema document) and

schemaUrl (a pointer to an externally hosted schema) are mutually exclusive on each event

type. Report, per eventType, which one it carries. Both are optional, so an event type with

neither is valid (report it neutrally); only an event type carrying both is invalid.

• Schema formats and versions — for each entry under schemas, report its format (e.g.

JsonSchema) and the number of versions. Use this to confirm the catalog uses a consistent

format and to spot schemas with zero or unexpectedly many versions.

• Category mix — summarize the eventTypeCategory distribution (EventType vs

BusinessEventType) so the user can confirm the catalog matches its intended purpose.

# Given the decoded definition JSON in $DEF (see Get Event Schema Set Definition),
# list each event type and whether it uses an inline schema or a schemaUrl:
echo "$DEF" | jq -r '(.eventTypes // [])[]
  | "\(.id): \(.eventTypeCategory) [\(.format)] -> "
    + (if (.schema != null and .schemaUrl != null) then "BOTH schema and schemaUrl (invalid)" elif .schema != null then "inline schema" elif .schemaUrl != null then "schemaUrl=\(.schemaUrl)" else "no inline schema or schemaUrl" end)'

# Summarize schema formats and version counts:
echo "$DEF" | jq -r '(.schemas // [])[] | "\(.id): \(.format), \(.versions | length) version(s)"'

Report the findings as a short per-event-type summary plus a schema-format/version rollup. If the

workspace contains no Event Schema Set, report that none were found (this is not an error).

Must / Prefer / Avoid

Must

• Refuse write requests up front, before any listing or inspection — if the user asks

to create, add, update, modify, rename, or delete an Event Schema Set or an event

type/schema, state plainly that this skill is read-only (consumption-only) and cannot

perform writes, then direct them to the Fabric Event Schema Set authoring REST APIs.

Do NOT list or inspect items first, and do NOT proceed even if the target does not exist.

• Always pass --resource https://api.fabric.microsoft.com with az rest calls
• Always use JMESPath filtering to resolve workspace name → ID and item name → ID
• Handle pagination — check for continuationUri/continuationToken in list responses
• Poll LRO responses — long-running calls may return 202 Accepted

Prefer

• Use jq (bash) or ConvertFrom-Json (PowerShell) for parsing
• Decode/structure output into readable summaries before reporting to the user

Avoid

• Do NOT hardcode workspace or item IDs — always discover them via the API
• Do NOT modify the event schema set nor event schema with this consumption skill — a dedicated authoring skill is not yet available, so use the Fabric Event Schema Set authoring REST APIs for writes

Examples

Example 1 — List Event Schema Sets in a workspace

Prompt: "List all Event Schema Sets in my Analytics workspace."

Flow:

• Resolve the workspace name → ID via GET /v1/workspaces + JMESPath (see the Table of Contents' *Finding Workspaces and Items in Fabric* reference).
• GET /v1/workspaces/${WORKSPACE_ID}/eventSchemaSets.
• Report each item's displayName and id (handle pagination via continuationToken).

Example 2 — Inspect an Event Schema Set's properties

Prompt: "Show the OneLake path and sensitivity label of the orders-catalog Event Schema Set in Analytics."

Flow:

• Resolve workspace ID, then resolve the item ID by filtering the list on displayName=='orders-catalog'.
• GET /v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}.
• Summarize displayName, description, properties.oneLakeRootPath, and sensitivityLabel.id.

Example 3 — Decode a definition and summarize event types & schemas

Prompt: "Decode the definition of the orders-catalog Event Schema Set and tell me its event types and schemas."

Flow:

• Resolve workspace ID and item ID (as above).
• POST /v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}/getDefinition (send an empty {} body; poll the Location header if it returns 202).
• Select the schema part (.path != ".platform"), base64-decode its payload, and parse the JSON.
• Enumerate eventTypes (id, category, format, inline schema vs schemaUrl) and schemas (id, format, version count).

Example 4 — Get a specific version of a schema

Prompt: "Get version v2 of schema BicycleSchema in the orders-catalog Event Schema Set in Analytics."

The user supplies the Event Schema Set name, a schema id, and a version id. Each version is an object with a required, stable string id (e.g. v1, v2) — select the version by that id, not by array position.

Flow:

• Resolve the workspace ID, then resolve the Event Schema Set item ID by filtering the list on displayName. If no item matches, report that the Event Schema Set was not found and stop.
• POST /v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}/getDefinition (send an empty {} body; poll the Location header if it returns 202), select the schema part (.path != ".platform"), base64-decode its payload, and parse the JSON.
• Find the entry in schemas whose id equals the requested schema id (use null-safe access — schemas may be absent). If no schema matches, report the requested id was not found, list the available schema ids, and stop.
• In that schema's versions array (null-safe), find the version whose id matches the requested version id — e.g. (.versions // [])[] | select(.id == $versionId). If no version has that id, do not silently pick another. Tell the user the requested version id was not found, list the available version ids, and ask whether they want:
• the latest version (the last entry, (.versions // [])[-1]),
• a different version id they specify, or
• to abort.

Proceed only once the user chooses (and re-validate their new choice). If the schema has no versions at all, report that and stop.

• Report the selected version's id, format, and schema document. This is read-only — never mutate the item.

Example 5 — List business events (vs regular events)

Prompt: "List all business events in the orders-catalog Event Schema Set in Analytics."

Business events are not a separate collection — they are eventTypes entries whose eventTypeCategory is BusinessEventType. Regular events are those with eventTypeCategory set to EventType or the field absent (it is optional).

Flow:

• Resolve the workspace ID and the Event Schema Set item ID (as above).
• POST /v1/workspaces/${WORKSPACE_ID}/eventSchemaSets/${ITEM_ID}/getDefinition (send an empty {} body; poll the Location header if it returns 202), select the schema part (.path != ".platform"), base64-decode its payload, and parse the JSON into $DEF.
• Filter the eventTypes array by category (use null-safe access — eventTypes may be absent):
• Business events: echo "$DEF" | jq -r '(.eventTypes // [])[] | select(.eventTypeCategory == "BusinessEventType") | .id'
• Regular events (symmetric): replace the predicate with select((.eventTypeCategory // "EventType") != "BusinessEventType").
• Report each matching event's id, format, and whether it carries an inline schema or a schemaUrl. If none match, report that the schema set has no business events (this is not an error). Read-only — never mutate the item.

Agent Integration Notes

• This skill is read-only — it does not create, alter, or delete items.
• For authoring operations, a dedicated authoring skill is not yet available — use the Fabric Event Schema Set authoring REST APIs directly.
• For cross-workload orchestration, delegate to the FabricDataEngineer agent.