Weaver documents¶
This section specifies how to author files that Weaver discovers as declarations. It covers paths, filenames, metadata, authored bodies, defaults and operation participation. The Python API reference instead specifies public classes, constructors and runtime methods; a Python-authored document must satisfy both surfaces without duplicating their full specifications here.
Document model¶
Data/validation declarations have four parts:
- Path — selects the owning logical item and, for most kinds, the declaration family.
- Kind — selected by the single ID key in object metadata, by the shortcut filename, by
schemas/, or byprogrammables/. - Metadata — YAML in a Python module docstring or opening SQL
/* ... */comment; shortcut, schema and programmable forms have their own schemas. - Body — Python class, SQL program, shortcut declarations, schema YAML or one Warehouse procedure statement.
Check and Build inspect data/validation Python structure statically without importing those authored classes. Power BI annotation files are a separate trusted-code surface loaded during project parsing; Build executes their transformations. Catalogue-backed Load/Test use installed definitions; source/file Test instead reads selected project validations.
The first two path components are exactly Lakehouse/<Item> or Warehouse/<Item>. Lakehouse data documents live directly in Tables/ or Files/; Warehouse Tables and Views live at the item root. Tests, Assumptions, schema metadata and Warehouse programmables live directly in their named directories, with no nested declaration directories.
A Lakehouse lib/ tree and each item shortcut file are supporting source, not independently selectable documents. Other files become declarations only in a supported location and form.
Supported forms¶
| Kind | Lakehouse | Warehouse |
|---|---|---|
| Table | Python or Spark SQL in Tables/ |
T-SQL at the item root |
| Folder | Python in Files/ |
Not supported |
| View | Spark SQL in Tables/ |
T-SQL at the item root |
| Test | Python or Spark SQL in tests/ |
T-SQL in tests/ |
| Assumption | Python or Spark SQL in assumptions/ |
T-SQL in assumptions/ |
| Shortcut | shortcuts.py |
shortcuts.yml |
| Schema metadata | YAML in schemas/ |
YAML in schemas/ |
| Warehouse programmable | Not supported | T-SQL in programmables/ |
Python object and validation filenames are Schema__Object.py; SQL filenames are Schema.Object.sql. The metadata ID is Schema.Object. Filename, ID, kind-specific directory and directly declared Weaver class must agree exactly, including case. Duplicate identities and case-only collisions are errors.
The owning item selects the SQL dialect: Lakehouse .sql is Spark SQL; Warehouse .sql is T-SQL. A suffix does not select another dialect.
Metadata and bodies¶
Object and validation metadata is a YAML mapping in the first module docstring or opening SQL block comment. It must contain exactly one kind-specific ID key. Description is required for data objects and validations; data objects also require Lineage. See Common metadata for shared value syntax and each kind page for the complete accepted key set.
A Python file declares exactly one class that directly inherits its metadata kind. Helper classes may coexist. The class name equals the filename stem and implements the methods named on the kind page.
A SQL file starts with metadata and leaves the executable SQL as its body. Weaver validates the supported program shape statically; target-engine syntax and execution errors that require Fabric remain Build, Load or Test failures.
Dependencies¶
When Dependencies is absent, Weaver infers document dependencies from authored Python imports or SQL relation references. A present Dependencies key replaces inference; Dependencies: [] explicitly declares no dependencies. Entries are item-relative Schema.Object names and must resolve to objects or shortcut destinations in the same item. Tests and Assumptions may depend on data objects but cannot themselves be dependency targets.
Spark SQL Tables and Views still require an explicit Dependencies key, including Dependencies: []. Spark SQL Tests and Assumptions are validation documents and may omit it; Weaver then infers their SQL references.
Logical Shortcuts add cross-item edges. Physical references and physical Shortcuts have no project producer to order. Descriptive $... metadata references and foreign-key metadata do not create execution dependencies. Document and item dependency graphs must be acyclic; explicit replacement does not permit an item cycle.
Native Power BI definitions use their own discovery/layout, not a Table metadata header. Model-owned DAX validations use opening comment metadata; native TMDL policy and annotations have separate rules. A Report is a native definition, not a Python/SQL data document.
Page map¶
- Common metadata — shared text, references, revision notes and dependency syntax.
- Table — Python, Spark SQL and Warehouse Table declarations.
- Folder — Lakehouse file-set declarations.
- View — Spark SQL and Warehouse Views.
- Test — expected-versus-actual validations.
- Assumption — violating-row validations.
- Shortcut — exact Lakehouse Python and Warehouse YAML forms.
- Schema metadata — optional schema descriptions and empty-schema declarations.
- Warehouse programmable — authored stored procedures managed by Build.