Shared shapes

Four record shapes repeat across the template families. Learn them once and most of every family’s contract is already familiar.

The table reference

Every loading-family root that names a table (this, source, sources[], target) conforms to one shape: the table reference. Two rules hold everywhere it appears: columns is always an array (empty rather than omitted when genuinely unresolvable, so your template can iterate unconditionally), and source is always the identical object to sources[0], never a copy. Optional members appear only when the builder resolved real data; a builder never fabricates a value to fill a slot.

Field	Type	Meaning
name	string	The table’s name. Always present.
fqn	string	The table’s fully qualified name (catalog.schema.name). Always present.
columns[]	array	The table’s columns. Required as [] rather than omitted, so iteration never needs a guard.
columns[].name	string	Column name.
columns[].dataType	string	Declared data type.
columns[].isPrimaryKey	boolean	Whether the column is part of the primary key.
columns[].isNullable	boolean	Whether the column permits NULL.
columns[].custom	object?	Org-defined custom attribute values at column grain. Conditional: present only when resolved; keys without a live definition never appear.
ulid	string?	Conditional: present only when the reference resolved to a cataloged table.
layer	string?	Conditional: functional layer slug (source, landing, staging, persistentStaging, and so on).
parts.catalog	string	Conditional: the fully qualified name decomposed; emitted only by producers whose templates read it. Source-system tables never carry parts: they have no honest catalog, and fabricating one is forbidden.
parts.schema	string	Schema component.
parts.name	string	Table-name component.
primaryKeys	string[]?	Conditional: primary-key column names, when the producer supplies them.
businessKeys	string[]?	Conditional: business-key column names, when the producer supplies them. On the staging family this member is column objects instead; see that section.
custom	object?	Conditional: org-defined custom attribute values at table grain.

The family column

The staging family’s column objects carry more than the plain table-reference column: they are the full modeling-grade column, including keys, transformations, lineage, and profiling. Wherever a staging root exposes columns, businessKeys, diffAttributes, or systemColumns, the elements are this shape.

Field	Type	Meaning
name	string	Column name.
dataType	string	Declared data type.
ordinal	number	Column position; also the emitted sort order.
isPrimaryKey	boolean	Primary-key flag.
isBusinessKey	boolean	Business-key flag.
isNullable	boolean	Nullability; drives NOT NULL in staging DDL.
isSystem	boolean	Durable system-column marker set at write time.
ulid	string?	Column identifier, when the row carries one.
transformation	string?	Literal SQL transformation template, placeholders preserved.
transformationArg	string?	Resolved separator for a concatenated business-key column.
businessKey.separator	string?	Present only on a business-key column: the separator between constituents.
businessKey.constituents[].columnUlid	string	Constituent identity and order for the composed key.
isIgnored	boolean?	Excludes the column from emission.
changeType	string?	Change-tracking behavior marker (the legacy Ignore value also excludes).
referenceColumn	object?	Foreign-key target: columnUlid, columnFqn, columnExternalId, relationshipType.
sourceColumns[]	array?	Lineage mirror: the upstream columns this one derives from, each with an optional transform.
profile	object?	Resolved column statistics: stats, rowCount, profiledAt, measuredOn (tableFqn, layer), hops, crossedTransform. Unset until a profile exists on the lineage chain.
externalId	string?	External identifier, when imported with one.
custom	object?	Org-defined custom attribute values at column grain.

The aligned DDL column

Wherever a context carries a ready-to-emit CREATE TABLE block (the DDL family’s per-platform blocks, the Fabric staging load models), each column line is precomputed and aligned so the rendered DDL lines up without any template arithmetic. Emit definition and you get the finished line; the parts are there when you want to compose your own.

Field	Type	Meaning
name	string	The raw column name, unchanged.
safe	string	The sanitized name: everything outside letters, digits, underscore, and hyphen stripped.
quoted	string	The sanitized name wrapped in the platform’s identifier delimiters.
dataType	string	The rendered platform data type.
paddedName	string	quoted right-padded to the block’s name width.
paddedDataType	string	dataType right-padded to the block’s type width.
isNullable	boolean	Nullability as a truthiness test: an absent source flag reads as NOT NULL.
definition	string	The finished, right-trimmed column line: indent, padded name, padded type, and NOT NULL where applicable.

The enclosing block also carries alignment.nameWidth (longest sanitized name plus the two delimiter characters) and alignment.dataTypeWidth (longest rendered type): the pad budgets the lines were built with.

Build settings

The build root is the organization’s (or project’s) build settings as one flat record. Every key is always present; a value that was never configured is the empty string, so templates test emptiness rather than existence.

Field	Type	Meaning
build.jobCluster	string	Orchestration: the job cluster specification.
build.gitSource	string	Orchestration: git source for the generated job.
build.assetBundlePath	string	Orchestration: asset bundle path.
build.buildOutputPath	string	Environment: root output path for generated artifacts.
build.repositoryName	string	Environment: target repository name.
build.notebookPath	string	Environment: notebook base path.
build.appendNotebookName	string	Environment: whether (and what) to append to a generated notebook name.
build.tempTableSchema	string	Environment: schema used for temp tables.
build.tableOwner	string	Environment: default table owner; the fallback for options.tableOwner.
build.tableProperties	string	Environment: default table properties clause.
build.readFilesOptions	string	Environment: default read_files options.
build.copyFormatOptions	string	Environment: default COPY INTO format options.
build.copyOptions	string	Environment: default COPY INTO copy options.
build.displayTimeZone	string	Environment: display time zone; the source of options.targetDisplayTimeZone.
build.dataTimeZone	string	Environment: time zone the stored data is in.
build.stagingMode	string	Data loading behavior: default staging mode before validation (a per-table override wins).
build.notebookLanguage	string	Data loading behavior: default notebook language (python or sql), used to select the notebook sibling.