sdk-contract-navigator

name	sdk-contract-navigator
description	Navigate the fabric-sdk-go SDK source to find the correct client factory, DTOs, item type constants, and pager methods for a given Fabric Item or non-item resource. USE FOR: identifying SDK packages, client factories, DTO structs, item type constants, and pager methods for any Fabric resource.

Skill: SDK Contract Navigator

Navigate the fabric-sdk-go SDK source to find the correct client factory, DTOs, item type constants, and pager methods for a given Fabric Item or non-item resource.

Prerequisites

• The user has identified a Fabric resource name (e.g. "Lakehouse", "Connection", "Shortcut")

Step 1 — Check SDK Version and Ensure Local Cache

Read go.mod in the provider repo root and find the github.com/microsoft/fabric-sdk-go dependency line to determine the current version:

github.com/microsoft/fabric-sdk-go <version>

Record the exact version string. All SDK browsing must target the version found in go.mod.

Important: Always read go.mod dynamically — never assume or hardcode the SDK version. It changes with dependency upgrades.

Then ensure the SDK is in the local Go module cache:

go mod download github.com/microsoft/fabric-sdk-go@<version>

The SDK source is now available at a deterministic path:

$(go env GOPATH)/pkg/mod/github.com/microsoft/fabric-sdk-go@<version>/

Primary source: Always use the local Go module cache for SDK browsing. It is faster and more reliable than GitHub MCP tools (get_file_contents returns large JSON blobs that are hard to search; search_code has indexing lag). Use read_file and Select-String (PowerShell) to browse and search SDK files directly.

Fallback only: Use GitHub MCP tools or pkg.go.dev only if the local cache is unavailable.

Useful search commands

# Find a struct definition
Select-String -Path "<sdk-path>\models.go" -Pattern "^type <StructName> struct"

# Find a field across all structs (with context)
Select-String -Path "<sdk-path>\models.go" -Pattern "<FieldName>" -Context 5

# List all structs matching a pattern
Select-String -Path "<sdk-path>\models.go" -Pattern "^type .*Connection.*struct" | Select-Object -ExpandProperty Line

# List directory contents
Get-ChildItem "<sdk-path>\fabric\" -Directory | Select-Object -ExpandProperty Name

Step 2 — Determine Resource Category

This provider has two resource categories with different SDK patterns:

Category A: Fabric Items (~60% of resources)

These use the generic fabricitem abstraction with per-item SDK packages.

Identifying trait: The SDK has a dedicated package under fabric/<itempackage>/ with its own client factory, and the provider service uses fabricitem.NewResource* constructors.

Examples: Lakehouse, Eventhouse, Data Pipeline, SQL Database, KQL Database, Notebook, Semantic Model, Spark Job Definition, ML Experiment, ML Model, Environment, Warehouse, etc.

Category B: Non-item resources (~40% of resources)

These use bespoke CRUD implementations with clients from the fabric/core/ package or other shared packages.

Identifying trait: The SDK client is accessed via fabcore.*Client (e.g. fabcore.ConnectionsClient, fabcore.ShortcutsClient, fabcore.GatewaysClient). The provider service implements resource.Resource directly without fabricitem generics.

Examples: Connection, Shortcut, Gateway, Workspace, Domain, Workspace Role Assignment, Connection Role Assignment, Gateway Role Assignment, Deployment Pipeline Role Assignment, Workspace Git, etc.

Proceed with Step 3A for Fabric Items or Step 3B for non-item resources.

---

Fabric Items Path (Category A)

Step 3A — Locate the SDK Package

The SDK organizes item packages under fabric/<packagename>/.

Using local module cache — List directories to find the item package:

Get-ChildItem "<sdk-path>\fabric\" -Directory | Select-Object -ExpandProperty Name

Look for a directory matching the item name (lowercased, no spaces). Common patterns:

Item Name	SDK Package Path
Lakehouse	fabric/lakehouse/
Eventhouse	fabric/eventhouse/
SQL Database	fabric/sqldatabase/
Data Pipeline	fabric/datapipeline/
KQL Database	fabric/kqldatabase/
Spark Job Definition	fabric/sparkjobdefinition/
Mirrored Database	fabric/mirroreddatabase/
Copy Job	fabric/copyjob/

Step 4A — Identify the Client Factory

Read the SDK package's client factory file (usually client_factory.go) from the local cache. The pattern is:

fab<package>.NewClientFactoryWithClient(fabricClient).NewItemsClient()

For example:

• fablakehouse.NewClientFactoryWithClient(fabricClient).NewItemsClient()
• fabeventhouse.NewClientFactoryWithClient(fabricClient).NewItemsClient()

Step 5A — Identify CRUD Methods

Read the items client file (usually items_client.go) for these methods:

Method Type	Pattern	Example
Get	client.Get<ItemName>(ctx, workspaceID, itemID, nil)	client.GetLakehouse(ctx, wID, iID, nil)
List pager	client.NewList<ItemNames>Pager(workspaceID, nil)	client.NewListLakehousesPager(wID, nil)
Create	client.Create<ItemName>(ctx, workspaceID, payload, nil)	client.CreateLakehouse(ctx, wID, payload, nil)
Update	client.Update<ItemName>(ctx, workspaceID, itemID, payload, nil)	client.UpdateLakehouse(ctx, wID, iID, payload, nil)
Delete	client.Delete<ItemName>(ctx, workspaceID, itemID, nil)	client.DeleteLakehouse(ctx, wID, iID, nil)

Also check for definition methods (indicates definition or *-definition-* archetype):

• client.Get<ItemName>Definition(ctx, workspaceID, itemID, nil)
• client.Update<ItemName>Definition(ctx, workspaceID, itemID, payload, nil)

Step 6A — Identify the ItemType Constant

The item type constant lives in the core package (fabric/core/), typically in constants.go or models.go:

fabcore.ItemType<ItemName>

Examples: fabcore.ItemTypeLakehouse, fabcore.ItemTypeEventhouse, fabcore.ItemTypeSQLDatabase

Step 7A — Identify DTO Structs

Read the SDK package's models.go file for these key structs:

DTO	Purpose	How to Identify
Main item struct	Top-level item (e.g. Lakehouse)	Has fields: ID, DisplayName, Description, WorkspaceID, Properties
Properties	Read-only properties from Get response	Struct named Properties with server-computed fields
CreationPayload	Create-time configuration	Struct named CreationPayload with user-settable fields

Also look for:

• Enum types — Any type <Name> string with Possible<Name>Values() func
• Nested structs — Structs referenced as pointer fields within Properties

Step 8A — Determine the Item Archetype

Use the "Item Archetypes" table in .github/instructions/fabric-item-patterns.instructions.md to match SDK capabilities to the correct archetype.

How to check:

• Has Properties → The Get response struct has a Properties field of a named struct type
• Has CreationPayload → A CreationPayload struct exists in the package
• Has Definition → The items client has GetDefinition / UpdateDefinition methods

---

Non-item resources path (Category B)

Step 3B — Locate the SDK Client

Non-item resources typically use clients from the fabric/core/ package. For the SDK client mapping, see the "SDK Client Mapping" table in .github/instructions/non-item-patterns.instructions.md.

Client access pattern:

client := fabcore.NewClientFactoryWithClient(fabricClient).NewConnectionsClient()

Step 4B — Identify CRUD Methods

Non-item clients have bespoke method names. Read the client source to find:

• Create/Get/Update/Delete methods
• List pager methods
• Any sub-resource methods (e.g. role assignments)

Step 5B — Identify DTO Structs

Read fabric/core/models.go or the specific client models for:

• Request/Response structs (e.g. CreateConnectionRequest, Connection)
• Nested configuration structs
• Enum types

---

Output Format

For Fabric Items (Category A)

Field	Value
Category	Fabric Item
SDK Version	<version from go.mod>
SDK Package	github.com/microsoft/fabric-sdk-go/fabric/<package>
Import Alias	fab<package>
Client Factory	fab<package>.NewClientFactoryWithClient(fabricClient).NewItemsClient()
Get Method	client.Get<ItemName>(ctx, workspaceID, itemID, nil)
List Pager	client.NewList<ItemNames>Pager(workspaceID, nil)
ItemType Constant	fabcore.ItemType<ItemName>
Archetype	basic / definition / properties / etc.
Properties DTO	fab<package>.Properties — list fields
CreationPayload DTO	fab<package>.CreationPayload — list fields (or "N/A")
Enum Types	List any enum types with their possible values

For non-item resources (Category B)

Field	Value
Category	Non-item (bespoke CRUD)
SDK Version	<version from go.mod>
SDK Package	github.com/microsoft/fabric-sdk-go/fabric/core (or other)
Import Alias	fabcore (or other)
Client	fabcore.<Resource>Client
CRUD Methods	List all relevant methods
Request DTOs	List create/update request structs with fields
Response DTOs	List response structs with fields
Enum Types	List any enum types with their possible values

Go Struct Fields

For each DTO struct found, list all fields with their Go types. Example:

type Properties struct {
    OneLakeFilesPath      *string                  `json:"oneLakeFilesPath,omitempty"`
    OneLakeTablesPath     *string                  `json:"oneLakeTablesPath,omitempty"`
    SQLEndpointProperties *SQLEndpointProperties   `json:"sqlEndpointProperties,omitempty"`
    DefaultSchema         *string                  `json:"defaultSchema,omitempty"`
}

The output from this skill feeds directly into #skill:schema-model-generator and #skill:itemgen-command-builder.