Skip to main content
Schema metadata defines column names, types, nullability, descriptions, and column audits. It can live inline in one MODEL() header or in a reusable SCHEMA() declaration.

​
Inline columns

Use inline columns for metadata owned by one model:
See Audits for built-in audits, custom audits, arguments, severity, and incremental run scope.

​
Reusable schemas

When multiple models implement the same relation shape, declare it once under schemas/. SQLBuild discovers schema files recursively and makes public names available throughout the project.
Bind a model with model_schema:
schema staging selects the warehouse destination schema. model_schema order selects reusable column metadata. The reusable description becomes the model description when the model does not declare one. A model-owned description takes precedence.

​
Model-local columns

A bound model may add output columns that are not part of the reusable shape:
Resolved schema columns retain their order and new model-local columns follow them. Use a named child schema when an extension is reusable; use inline columns for an extension owned by one model.

​
Model-specific column audits

Audits in a reusable schema apply to every bound model. A model can add stricter audits to an inherited column by naming that column and declaring only audits:
The effective order_id keeps the reusable type, nullability, description, and not_null audit, then adds unique. A model cannot remove reusable audits or override inherited metadata. An inherited-column entry containing type, nullable, or description fails compilation. Identical audit instances are deduplicated.

​
Inheritance

A reusable schema may extend one parent with additional columns:
Inheritance may be transitive. Parent columns resolve before child columns. An inherited column cannot be redeclared or overridden in a child schema. SQLBuild rejects unknown parents, cycles, case-insensitive duplicates, and multiple parents. Physical SQL output order is not currently enforced. Static contract analysis matches names and checks declared types and proven non-nullability. Runtime exact-contract validation matches names and types but does not validate nullability.

​
Contracts and planning

contract enforced treats the complete named-plus-local declaration as the exact output shape. With contract none, the default, SQLBuild checks declared columns when static inference is available and permits additional output columns; it does not add a runtime shape requirement. See Contracts. For models bound to a reusable schema, effective column names, types, nullability, and enum members participate in model version identity. Changing those fields on a parent therefore affects models bound through descendants. Descriptions do not change model identity. Audits have their own audit-gate identities, so audit changes invalidate reusable audit results without changing the model version itself.

​
Limitations

Reusable schemas intentionally support a narrow ownership model:
  • One optional parent, with transitive inheritance.
  • Additive child and model-local output columns.
  • Audit-only model augmentation of inherited columns.
  • No general column overrides, multiple inheritance, composition, mixins, parameters, or generated projections.
  • No physical output ordinal enforcement.