Loom YAML Schema¶

A loom is a deployment unit that groups weaves into an ordered execution sequence. It defines which weaves run, optional shared defaults, and runtime settings that cascade down through weaves to threads.

Top-level keys¶

Key	Type	Required	Default	Description
`config_version`	`string`	yes	--	Schema version identifier (e.g. `"1.0"`)
`name`	`string`	no	`""`	Human-readable loom name
`weaves`	`list[WeaveEntry or string]`	yes	--	Weave entries. Strings are shorthand for `{ name: "<value>" }`. Use `ref` for an external file, `name` alone for `<name>.weave` in the project root, or `name` plus a weave body for an inline weave.
`defaults`	`dict[string, any]`	no	`null`	Default values cascaded into every weave and thread. `audit_columns` and `exports` use additive merge (see Exports guide).
`params`	`dict[string, ParamSpec]`	no	`null`	Typed parameter declarations scoped to this loom
`execution`	`ExecutionConfig`	no	`null`	Runtime settings: `log_level`, `trace`, `max_parallel_threads`, `capture_samples`. Merges field-level with weave blocks (weave-set fields win). See the Execution Settings guide.
`naming`	`NamingConfig`	no	`null`	Naming normalization cascaded to weaves and threads
`column_sets`	`dict[string, ColumnSet]`	no	`null`	Named column sets cascaded to weaves. Weave-level definitions with the same name override loom-level definitions. Column sets can read their mapping table via a loom-level `connections:` entry — see Connections guide: Column sets via connections. See Weave schema: column_sets for field details.
`lookups`	`dict[string, Lookup]`	no	`null`	Loom-level lookup definitions. Merged with weave-level lookups (weave wins on name collision). See Weave schema: lookups for field details.
`variables`	`dict[string, VariableSpec]`	no	`null`	Loom-level variable declarations. Resolved before `pre_steps` execution.
`pre_steps`	`list[HookStep]`	no	`null`	Hook steps to run before any weave executes. See Weave schema: pre_steps / post_steps for field details.
`post_steps`	`list[HookStep]`	no	`null`	Hook steps to run after all weaves complete.
`audit_templates`	`dict[string, AuditTemplate]`	no	`null`	Named audit column templates cascaded to all weaves and threads. Weave and thread definitions override loom-level definitions with the same name. A flat `dict[string, string]` shorthand is also accepted. See Audit Templates guide.
`connections`	`dict[string, OneLakeConnection]`	no	`null`	Named connection definitions cascaded to weaves and threads. Lower levels override by name. See Connections guide.

weaves (WeaveEntry)¶

Each entry in the weaves list is either a plain string (shorthand) or a WeaveEntry object. An entry takes one of three forms:

ref — an external .weave file, relative to the project root.
name alone — the weave file <name>.weave in the project root. If that file does not exist, loading fails with an error naming it.
name plus a weave body — an inline weave defined in the loom. The body takes the same keys as a .weave file, including config_version and threads; threads can be inline or use ref. Errors in an inline weave name the loom file.

Key	Type	Required	Default	Description
`ref`	`string`	no	`null`	Path to an external `.weave` file, relative to the project root. Mutually exclusive with `name`.
`name`	`string`	no	`""`	Weave name. Without `ref`, names `<name>.weave` in the project root or an inline weave; derived from the filename stem when using `ref`.
`condition`	`ConditionSpec`	no	`null`	Conditional execution gate

weaves.condition (ConditionSpec)¶

Key	Type	Required	Default	Description
`when`	`string`	yes	--	Condition expression. Supports `${param.x}` references, `table_exists()`, `table_empty()`, `row_count()`, and boolean operators.

lookups¶

Loom-level lookup definitions shared across all weaves. The structure is identical to weave-level lookups. When a weave defines a lookup with the same name, the weave-level definition wins.

lookups:
  dim_calendar:
    source:
      type: delta
      alias: ref.dim_calendar
    key: [date_key]
    values: [fiscal_year, fiscal_quarter]
    materialize: true
    strategy: broadcast

variables¶

Loom-level typed variable declarations. Variables can be set by sql_statement hook steps via set_var and referenced in downstream config as ${var.name}. The structure is identical to weave-level variables.

variables:
  pipeline_start:
    type: timestamp
    default: null

pre_steps / post_steps¶

Hook steps that run before any weave executes (pre_steps) or after all weaves complete (post_steps). The structure is identical to weave-level hooks.

post_steps run after all weaves complete, including when a weave fails and stops the loom. They do not run if an earlier lifecycle phase (such as pre_steps or lookup materialization) raises an unhandled exception.

These lists are not cascaded to child weaves. Each level runs its own list.

pre_steps:
  - type: quality_gate
    name: check_upstream_freshness
    check: source_freshness
    source: raw.events
    max_age: "1h"

post_steps:
  - type: log_message
    message: "Loom complete."
    level: info

Configuration cascade¶

Defaults flow downward through the hierarchy:

Loom defaults
  --> Weave defaults (override loom)
    --> Thread config (override weave)

The most specific level always wins.

The top-level execution: block is the exception: it is not part of defaults, loom and weave blocks merge field-level (an explicitly set weave field wins), and it never applies at thread scope. See the Execution Settings guide.

Complete example¶

config_version: "1.0"
name: daily_etl

weaves:
  - ref: ingest_raw.weave
  - ref: build_curated.weave
    condition:
      when: "${param.run_curated} == 'true'"
  - ref: publish_marts.weave

defaults:
  write:
    mode: overwrite

params:
  run_curated:
    name: run_curated
    type: bool
    required: false
    default: true
    description: "Whether to run the curated layer"

execution:
  log_level: standard
  trace: true

naming:
  columns: snake_case
  tables: snake_case

Shorthand weave syntax¶

Weave entries can be plain strings when the weave lives in <name>.weave in the project root and needs no condition:

weaves:
  - ingest_raw
  - build_curated
  - publish_marts

This is equivalent to:

weaves:
  - name: ingest_raw
  - name: build_curated
  - name: publish_marts

For external file references, use ref explicitly:

weaves:
  - ref: ingest_raw.weave
  - ref: build_curated.weave
  - ref: publish_marts.weave

Inline weave¶

An inline weave keeps a small weave in the loom file itself:

weaves:
  - ref: ingest_raw.weave
  - name: ops_audit
    config_version: "1.0"
    condition:
      when: "table_exists('ops.audit_events')"
    threads:
      - ref: threads/audit_events.thread
      - name: audit_summary
        config_version: "1.0"
        sources:
          events:
            type: delta
            alias: ops.audit_events
        target:
          alias: ops.audit_summary
        dependencies:
          - audit_events