version: "1.0.0" 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:

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:

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:

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)

For non-item resources (Category B)

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.