Skip to content

Workspace configuration

A workspace configuration binds logical Weaver items to physical Fabric items. It also selects the catalogue, optional Spark runtime and optional Mirror source used in that estate.

File and discovery

The conventional filename is exactly workspace-config.yml. Automatic discovery checks only the process's current working directory. It does not search parent directories, inspect the Build source path or try other filenames.

--workspace-config PATH selects that file instead of the discovered file. The path may name any file; its basename has no semantic meaning.

The file must contain one YAML mapping. An empty document, YAML null and a mapping without workspace all fail because workspace is required.

Complete shape

workspace: Parcel Operations
catalogue: Warehouse/ParcelCatalogueDev
environment: Platform Runtimes/ParcelRuntime
mirror: Warehouse/ParcelCatalogue

execution:
  build:
    warehouse_concurrency: 2
    spark_concurrency: 4
    onelake_concurrency: 8
    shortcut_concurrency: 2
  run:
    spark_concurrency: 4
    warehouse_concurrency: 4

targets:
  Lakehouse/Landing: ParcelLandingDev
  Warehouse/Operations:
    name: ParcelOperationsDev

The top-level keys listed below are accepted. Unknown keys are rejected at the top level and inside execution or a target mapping. The retired top-level keys lakehouses and warehouses are rejected; use targets.

Top-level keys

Key Shape Required Default Meaning and restrictions
workspace non-empty string yes — Fabric workspace in which the workload, catalogue and targets are resolved. Fabric-name validation applies.
catalogue Warehouse/Name no unset Warehouse holding the Weaver catalogue. The kind must be the literal Warehouse; a workspace-qualified value is not accepted here.
environment Environment or Workspace/Environment no unset Published Fabric Environment attached to Spark work. A qualified reference may select an Environment owned by another workspace. This key does not create or publish it.
mirror Warehouse/Name or Workspace/Warehouse/Name no unset Source catalogue for Mirror and mirrored-state reads. Although the qualified form parses, Mirror and mirrored-state reads reject a source outside the resolved workspace.
execution mapping no build/run defaults below Workspace-level resource limits.
data_sources mapping no {} Shared M expression name to typed Warehouse/Name or Lakehouse/Name; explicit Build mappings override the same expression.
targets mapping from logical item to target declaration no {} Build and Mirror destination bindings. An operation that needs an absent binding fails when resolving that item.

workspace, Environment components, catalogue names and physical target names use Fabric-name validation. Leading and trailing whitespace is removed. A name must not be empty, consist only of dots, or contain /, \\, :, *, ?, ", <, > or |. The / characters shown in catalogue and Environment references are separators between validated components.

execution

execution:
  build:
    warehouse_concurrency: 2
    spark_concurrency: 4
    onelake_concurrency: 8
    shortcut_concurrency: 2
  run:
    spark_concurrency: 4
    warehouse_concurrency: 4

These are defaults, not required project settings. Omitted groups/keys retain their defaults. Each value must be a positive integer; booleans are rejected. Only build and run groups and the keys above are accepted. Build limits also govern physical Wipe/Mirror actions. Warehouse limits apply per Warehouse; Spark limits share an application, not separately provisioned clusters. OneLake/shortcut limits concern their respective actions, not every nested HTTP request.

Build, Load and Test also accept an invocation --concurrency N / Python concurrency=N. It caps total scheduled actions/nodes across that call while resource limits and dependency ordering still apply. Omission retains operation/configured defaults. The call does not rewrite configuration or retarget a retained bundle. Source/file Tests are serial by default and use the scheduler when an explicit concurrency is supplied. There is no execution.test, per-target execution mapping or --spark-concurrency flag. The retired execution.parallel_workers is rejected.

data_sources

data_sources:
  ParcelSource: Warehouse/Operations

Keys are exact shared M expression names, non-empty with no surrounding whitespace. Values are typed Lakehouse/Warehouse item names; unsupported types, malformed identities and duplicate explicit mappings fail. Logical items resolve through selected Build bindings or configured targets; otherwise the typed name addresses a physical source. Explicit --data-source ParcelSource=Warehouse/Other overrides configuration. An explicit mapping that reaches no selected model expression fails. This is supported typed source substitution, not arbitrary M replacement or credential creation. See Power BI source mapping.

targets

Each key is an exact logical item identity:

Lakehouse/Name
Warehouse/Name
SemanticModel/Name
Report/Name

Each value has one of two shapes:

# Short form
Lakehouse/Landing: ParcelLandingDev

# Long form
Warehouse/Operations:
  name: ParcelOperationsDev

The short-form string and long-form name are physical Fabric item names, not typed target references. The logical key supplies the Lakehouse, Warehouse, SemanticModel or Report kind. The long form accepts only required name; nested execution settings are rejected.

For example:

workspace: Parcel BI Development
targets:
  SemanticModel/Parcel: Parcel_Dev
  Report/Parcel: Parcel_Report_Dev

No catalogue or Environment is required for this Power BI deployment configuration. Explicit catalogue-free model refresh and source/file Tests resolve configured names or fall back to the logical model/item name. Build uses configured/explicit destinations and requires a binding for each selected item; do not infer missing Build bindings from refresh fallback. Reports have no Load/Test.

targets may be absent or empty. Two logical items may parse with the same physical name, but one Build or Mirror cannot install two ordinary items of the same kind into one destination.

What each binding controls

  • workspace chooses the Fabric workspace context.
  • catalogue is a separate Warehouse binding for installed definitions and operational state. It is never an implicit target for a logical Warehouse.
  • targets supplies physical destinations to Build and Mirror. Build records the settled bindings in the catalogue.
  • Catalogue-backed Load, Test and Health read installed bindings, not replacement targets from configuration. Catalogue-free refresh and source/file Test instead use configured target resolution.
  • environment selects a published runtime for Spark work. It is neither a target nor a publication instruction.
  • mirror identifies a source catalogue. Loading the configuration neither reads that catalogue nor runs Mirror.

Workspace resolution and precedence

An operation resolves its base workspace in this order:

  1. an explicit --workspace and/or --workspace-config;
  2. the Workspace already owned by a supplied Session;
  3. workspace-config.yml in the current working directory;
  4. the current Fabric notebook workspace;
  5. an error if no workspace can be resolved.

The details are consequential:

  • --workspace-config FILE loads FILE and bypasses automatic discovery.
  • --workspace NAME without --workspace-config bypasses automatic discovery and creates a workspace with no configured catalogue, Environment, Mirror source, execution settings or targets.
  • Supplying both uses the file as the base and replaces only its workspace value.
  • Explicit --catalogue and --environment values replace the corresponding value on whichever base won, including a Session-owned Workspace.
  • A Session is considered only when neither an explicit workspace nor an explicit configuration was supplied.
  • A discovered file is considered before Fabric notebook context. Discovery is not based on the project directory passed to build SOURCE.

Health has no Environment argument because it executes no authored Spark work. Check reads project source locally and does not resolve this configuration.

Configuration selection

Development and production are ordinary files selected by path. Their filenames and suffixes have no recognised meaning.

workspace-production.yml
workspace: Parcel Operations
catalogue: Warehouse/ParcelCatalogue
targets:
  Lakehouse/Landing: ParcelLanding
  Warehouse/Operations: ParcelOperations
workspace-development.yml
workspace: Parcel Operations
catalogue: Warehouse/ParcelCatalogueDev
mirror: Warehouse/ParcelCatalogue
targets:
  Lakehouse/Landing: ParcelLandingDev
  Warehouse/Operations: ParcelOperationsDev

weaver build . --workspace-config workspace-development.yml
weaver load --workspace-config workspace-development.yml
weaver test --workspace-config workspace-development.yml

Both files bind the same logical items. Selecting a file changes the physical estate addressed by the operation; it does not rename the project, items or documents.

Mirror source and destination resolution

Mirror resolves its two catalogue roles separately:

  1. source: explicit --mirror, then configured mirror, then configured catalogue;
  2. destination: explicit --catalogue, otherwise configured catalogue only when a configured mirror is present.

A configuration containing only catalogue therefore describes a possible source estate, not an inferred destination. The destination must be supplied separately. A configuration containing both uses mirror as the source and catalogue as the destination.

Both catalogues must resolve to distinct Warehouses in the selected workspace. A value such as Production/Warehouse/ParcelCatalogue is accepted by the configuration parser but rejected by Mirror when workspace is not Production; it does not enable cross-workspace mirroring. Destination targets also belong to the selected workspace because target declarations carry names, not workspace qualifiers.

The development example above is valid because its source catalogue, destination catalogue and destination targets all belong to Parcel Operations.

Validation boundary

Configuration loading validates YAML shape, accepted keys, logical item syntax, reference syntax, Fabric names and positive concurrency values. It does not contact Fabric. Existence, item kind, permissions, Environment publication state and catalogue compatibility are checked only by operations that use those references.

Operation-specific requirements remain separate:

  • catalogue-backed operations require a resolved catalogue;
  • Build and Mirror require a destination binding for each selected item unless ITEM=TARGET supplies it;
  • Build with no --item requires at least one configured target;
  • Mirror applies the source/destination rules above;
  • remote runtime work may require a published Environment.

See Fabric Environment definition, Shared selection and identity and the individual operation behaviour pages.