dbt charts YAML Schema Reference

Board

AuthoredBoard definition from YAML.

Field	Type	Optional	Description
title	str	✓	Dashboard title displayed at the top.
description	str	✓	Description text for the dashboard.
tags	list[str]	✓	Tags for categorization and search.
aliases	list[str]	✓	Additional URLs that redirect to this board's canonical file-path URL. Each entry must be absolute (leading /). Requests to these URLs are redirected (302) to the board's real path, query string preserved. Valid on .yml, .yaml, .md, and folder index.* boards.
text	str	✓	Markdown text content for text-only sections.
html_policy	enum: "none", "safe-subset", "trusted-raw"	✓	HTML rendering policy for the board's body text. One of: "none" (default) — HTML is escaped and rendered as plain markdown; "safe-subset" — reserved for a parser-checked allowlist (not yet enforced — currently renders as none); "trusted-raw" — raw HTML via foreignObject. TRUSTED-CONTENT ONLY: this is NOT a security sandbox. <script>/event-handlers are stripped as a best-effort guard, not a guarantee. Enable only on first-party boards you fully control.
source	str	✓	Default source name for all queries in this board. Inheritable via meta.yaml cascade.
cache	Cache	✓	Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade.
variables	dict[str, Variable | VariableRef]	✓	Variable definitions for dynamic filtering and UI controls.
queries	dict[str, SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef]	✓	Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.).
charts	dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | ChartRef]	✓	Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order.
rows	list[str | Board | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart]]	✓	Vertical stack layout: list of chart names or inline chart/board definitions.
cols	list[str | Board | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart]]	✓	Horizontal layout: list of chart names or inline chart/board definitions.
grid	GridLayout	✓	CSS-grid style layout with explicit row/column placement.
tabs	TabLayout	✓	Tabbed navigation layout where each tab contains its own layout.
card_gap	bool	✓	When True, adds gap between cards. Default: cards are edge-to-edge (0 gap).
chart_focus	str	✓	Render only this named chart with its dependent variables (useful for embedding or SVG export).
details	BoardDetails	✓	Collapsible section metadata. String shorthand: details: 'text' → BoardDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}.
id	str	✓	Explicit ID for this board. Auto-generated from filename if omitted.
style	Style	✓	Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child boards.
width	str | int	✓	Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root board there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.frame.width') — percentages are rejected there since there's nothing to size relative to.
height	str | int	✓	Height when nested (e.g., '300px' or an integer in pixels).
visible	bool | str | SingleRowBoolProbe	✓	Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe.
extends	str | list[str] | enum: "cream", "editorial", "neon", "plain", "solid", "stark", "vivid"	✓	Board name(s) or relative path(s) this board inherits from, low to high priority. A built-in theme name resolves it directly.
auto_link	bool	✓	When True, table charts with no explicit link: automatically link each row to its canonical /data/<source>/<schema>/<table>/detail/ page. Default off. Explicit link: always wins; set link: ~ to suppress per chart.

Cache

Cache policy at one scope: cache: 1h / forever / true / false (the only opt-out).

Field	Type	Optional	Description
ttl	str | enum: "forever"	✓	Expire cached results after this wall-clock age (lazy: the next read recomputes). Short-duration string: units s/m/h/d/w, m = minutes, compound allowed ('1h30m'). Omit to inherit from the parent scope; write 'forever' to override an inherited ttl with never-auto-expire (manual refresh always remains available).

Variable

Variable definition from YAML.

Field	Type	Optional	Description
input	enum: "auto", "select", "multiselect", "input", "text", "number", "textarea", "slider", "range", "date", "datepicker", "daterange", "checkbox", "radio"	✓	UI control type (select, multiselect, slider, daterange, etc.). 'auto' detects from options.
label	str	✓	Display label shown above the input control.
description	str	✓	Help text shown below the input control.
default	Any	✓	Default value used when no URL param is set.
placeholder	str	✓	Placeholder text shown in the input when empty.
required	bool	✓	When True, a value must be provided before queries execute.
visible	bool	✓	When False, the variable is not rendered in the UI but can still be set via URL params.
enabled	bool | str | SingleRowBoolProbe	✓	Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default).
column	str	✓	Table column to draw option values from, as 'table.column'. The table may be schema-qualified ('schema.table.column') when it is not in the connection's default schema.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery	✓	Query name or inline query definition for populating options.
dimension	str	✓	MetricFlow dimension name for populating options.
measure	str	✓	MetricFlow measure name for populating options.
model	str	✓	dbt model name for populating options.
options	VariableOptions	✓	Static or query-driven option list configuration.
data_type	str	✓	Upstream data-type hint preserved through migrations (e.g. 'string', 'number'). Informational; not currently consumed at compile time.
min	int | float	✓	Minimum value for slider/range inputs.
max	int | float	✓	Maximum value for slider/range inputs.
step	int | float	✓	Step size for slider/range inputs.
operator	str	✓	SQL operator used when generating filter expressions (e.g., '=', 'IN', 'LIKE').

SqlQuery

Raw SQL query — the default query type.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "sql"	✓	Query adapter type.
sql	str	✓	SQL query string. Supports Jinja2 templates referencing variables.
setup_sql	str	✓	Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION).
target	str	✓	dbt target name for queries against a dbt_profile source (defaults to 'dev').

MetricflowQuery

dbt Semantic Layer (MetricFlow) query.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "metricflow"	✓	Query adapter type.
metrics	list[str]	✓	MetricFlow metric names to query.
dimensions	list[str]	✓	MetricFlow dimensions to include in the result.
time_grain	enum: "day", "week", "month", "quarter", "year"	✓	MetricFlow time grain for time-series dimensions (day, week, month, quarter, year).
where	list[str]	✓	SQL predicates over the query's MetricFlow group-by names. Literal predicates (no Jinja) bake into MetricFlow at compile time and may reference any dimension; predicates with {{ }} resolve per render and must reference a selected dimension (in dimensions: or the time_grain column).
limit	int	✓	Maximum number of rows returned.

HttpQuery

REST API query.

Field	Type	Optional	Description
url	str		HTTP endpoint URL for REST API queries.
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "http"	✓	Query adapter type.
method	enum: "GET", "POST", "PUT", "DELETE", "PATCH"	✓	HTTP method (GET, POST, PUT, DELETE, PATCH).
headers	dict[str, str]	✓	HTTP request headers.
params	dict[str, Any]	✓	HTTP query string parameters.
body	dict[str, Any] | str	✓	HTTP request body for POST/PUT queries.
limit	int	✓	Maximum number of rows returned.
json_path	str	✓	JSONPath expression to extract tabular data from the HTTP response.

ValuesQuery

Inline data authored as a list of row mappings.

Field	Type	Optional	Description
rows	list[dict[str, Any]]		Inline data rows (list of row dicts). Use the compact columns-and-values form instead when row values are positional.
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "values"	✓	Query adapter type.

CompactValuesQuery

Inline data authored as column names plus positional row values.

Field	Type	Optional	Description
columns	list[str]		Column names for the compact syntax. Every compact values query also requires values.
values	list[list[Any]]		Inline row-oriented data (list of lists) for the compact syntax. Every compact values query also requires columns.
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "values"	✓	Query adapter type.

SchemaQuery

dbt source schema query.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']).
cache	Cache	✓	Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "schema"	✓	Query adapter type.
schema	str	✓	Schema name for schema queries (YAML key: schema).
table	str	✓	Table name for schema queries.
column	str	✓	Column name for schema queries.

BarChart

Authored patch for bar and histogram charts.

Field	Type	Optional	Description
type	enum: "bar", "histogram"		Bar or histogram chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
style	BarChartStyle	✓	Chart-local style overrides.
layers	list[BarLayer | LineLayer | AreaLayer | ScatterLayer]	✓	Typed overlay layers on this chart.

LineChart

Authored patch for line charts.

Field	Type	Optional	Description
type	enum: "line"		Line chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
style	LineChartStyle	✓	Chart-local style overrides.
layers	list[BarLayer | LineLayer | AreaLayer | ScatterLayer]	✓	Typed overlay layers on this chart.

AreaChart

Authored patch for area charts.

Field	Type	Optional	Description
type	enum: "area"		Area chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
style	AreaChartStyle	✓	Chart-local style overrides.
layers	list[BarLayer | LineLayer | AreaLayer | ScatterLayer]	✓	Typed overlay layers on this chart.

ScatterChart

Authored patch for scatter charts.

Field	Type	Optional	Description
type	enum: "scatter"		Scatter chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
size	str	✓	Column used to size-encode data points (quantitative).
shape	str	✓	Column used to shape-encode data points (categorical).
style	ScatterChartStyle	✓	Chart-local style overrides.
layers	list[BarLayer | LineLayer | AreaLayer | ScatterLayer]	✓	Typed overlay layers on this chart.

HeatmapChart

Authored patch for heatmap charts.

Field	Type	Optional	Description
type	enum: "heatmap"		Heatmap chart type.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts.
style	HeatmapChartStyle	✓	Chart-local style overrides.

PieChart

Authored patch for pie and donut charts.

Field	Type	Optional	Description
type	enum: "pie", "donut"		Pie or donut chart type.
theta	str		Column for angular encoding in pie (arc) charts.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
color	str	✓	Color data channel: bare column name only.
total	ChartTotal	✓	Donut center total.
height	int | float	✓	Explicit chart height in pixels. Positive number only.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container.
style	PieChartStyle	✓	Chart-local style overrides.

KpiChart

Authored patch for KPI (key performance indicator) charts.

Field	Type	Optional	Description
type	enum: "kpi"		KPI chart type.
value	str		Column reference (string column name) for the headline number/text.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
label	str	✓	KPI label rendered above the headline value.
variant	enum: "stacked", "inline", "compact"	✓	Layout variant. 'stacked' (default) shows value, label, and support on three vertical lines. 'inline' lays value, label, and support out on a single baseline-aligned row. 'compact' is 2-column — big value on the left, up to two stacked lines on the right with the bottom line sharing baseline with the value; a lone support block splits across the two right-column lines.
support	KpiSupportConfig	✓	Optional support line beneath the KPI value.
style	KpiChartStyle	✓	Chart-local style overrides.
background	str | dict[str, Any]	✓	Gradient background channel — {column, scale} shape. Paints the card background by the value's position in the scale.

TableChart

Authored patch for table charts.

Field	Type	Optional	Description
type	enum: "table"		Table chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
style	TableChartStyle	✓	Chart-local style overrides.
rows	list[str]	✓	Fields whose distinct values form the row dimension of a pivot cross-tab. Each string is a column name from the query result. Omit for flat (non-pivot) tables.
columns	list[str]	✓	Fields whose distinct values become column headers in a pivot cross-tab. Multiple fields create a nested multi-dimension pivot (outer → inner). Omit for flat tables.
values	list[str]	✓	Measure fields that fill pivot cells. Each string is a column name from the query result. When omitted, all query columns not claimed by rows or columns are used.

PointMapChart

Authored patch for point_map and bubble_map charts.

Field	Type	Optional	Description
type	enum: "point_map", "bubble_map"		Point map or bubble map chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
projection	str | Projection	✓	Map projection name or Vega-Lite projection config.
color	str	✓	Color data channel: bare column name only.
geo	str | dict[str, Any]	✓	Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts.
geo_source	str	✓	Named geographic data source for loading GeoJSON boundaries.
lookup	str	✓	Data column to join against geographic data (map join key).
value	str	✓	Data column mapped to the fill color.
height	int | float	✓	Explicit chart height in pixels. Positive number only.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container.
latitude	str	✓	Column containing latitude values for point/bubble maps.
longitude	str	✓	Column containing longitude values for point/bubble maps.
size	str	✓	Data column used to scale bubble radius (quantitative). Only meaningful on bubble_map.
collapse	bool	✓	Collapse marks sharing an exact latitude/longitude into one mark sized by count. Mutually exclusive with size and with any color channel.
basemap	BasemapConfig	✓	Styled geographic background layer.
style	PointMapChartStyle	✓	Chart-local style overrides.

GeoshapeChart

Authored patch for map and geoshape charts.

Field	Type	Optional	Description
type	enum: "map", "geoshape"		Map or geoshape chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
projection	str | Projection	✓	Map projection name or Vega-Lite projection config.
color	str	✓	Color data channel: bare column name only.
geo	str | dict[str, Any]	✓	Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts.
geo_source	str	✓	Named geographic data source for loading GeoJSON boundaries.
lookup	str	✓	Data column to join against geographic data (map join key).
value	str	✓	Data column mapped to the fill color.
height	int | float	✓	Explicit chart height in pixels. Positive number only.
width	int | float	✓	Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container.
style	GeoshapeChartStyle	✓	Chart-local style overrides.

CalloutChart

Static callout/message chart. Minimal — no chrome, no styling, no query.

Field	Type	Optional	Description
type	enum: "callout"		Callout chart type.
message	str		Static message content.
title	str	✓	Optional chart title shown above the message.
style	CalloutChartStyle	✓	Chart-local style overrides (tone).
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.

SparkBarChart

Authored patch for spark_bar charts (compact horizontal bars).

Field	Type	Optional	Description
type	enum: "spark_bar"		SparkBar chart type.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | HttpQuery | ValuesQuery | CompactValuesQuery | SchemaQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis (label) column name.
y	str | list[str]	✓	Y-axis (value) column name(s).
style	SparkBarChartStyle	✓	Chart-local style overrides.

GridLayout

Grid layout configuration.

Field	Type	Optional	Description
items	list[GridItem]		List of grid items with position and span configuration.
columns	int	✓	Number of grid columns (default: 24).
row_height	str	✓	Default row height as a CSS value (e.g., '200px').
gap	enum: "sm", "md", "lg", "xl"	✓	Gap between grid cells (sm, md, lg, xl).
default_width	int	✓	Default column span for items that don't specify width.
default_height	int	✓	Default row span for items that don't specify height.

TabLayout

Tab layout configuration.

Field	Type	Optional	Description
items	list[TabItem]		List of tab items.
id	str	✓	Variable name and URL param base for tab selection (auto-generated if omitted).
position	enum: "top", "left"	✓	Tab bar position (top or left).
default	str	✓	Default tab title to activate on load.

BoardDetails

Collapsible section metadata for a board.

Field	Type	Optional	Description
summary	str		Label shown when the section is collapsed.
expanded_title	str	✓	Label shown when the section is expanded. Defaults to summary.
expanded	bool	✓	Whether the section is open by default.

Style

Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.

Field	Type	Optional	Description
frame	FrameStyle	✓	Board-level structural frame dimensions.
background	str	✓	Working-surface background color (board and card fills).
accent	str	✓	Accent color token cascaded to sparklines, bars, and focus rings.
muted	str	✓	Muted secondary-text color token (KPI support rows, table and spark subtitles).
font	RootFontStyle	✓	Root font configuration including emoji mode.
border	BorderStyle	✓	Default border style cascaded to all chart cards.
box_shadow	str	✓	CSS box shadow for chart cards; None means no shadow.
opacity	float	✓	Default mark opacity (0–1).
title	TitleStyle	✓	Board and board title style.
text	TextStyle	✓	Markdown and plain text content style.
placeholder	PlaceholderStyle	✓	Placeholder overlay style for empty charts.
charts	ChartsStyle	✓	Root of all chart-type styles and shared chart configuration.
layout	LayoutStyle	✓	Layout container styles (rows, cols, grid, tabs, details).
variables	VariablesStyle	✓	Variable controls chrome style.
page	PageStyle	✓	Page-level canvas style (behind the board).
footer	FooterStyle	✓	Page footer chrome visibility.
timestamp	TimestampStyle	✓	Data-freshness chrome: visibility, placement, format, and font.
formats	dict[str, str]	✓	Format alias map; None means no aliases at this cascade level.
palettes	dict[str, one of: 'category-6-tonal-blue', 'category-6-tonal-brown', 'category-6-tonal-green', 'category-6-tonal-orange', 'category-6-tonal-purple', 'dbt-creams', 'dbt-div-blue-red', 'dbt-div-blue-red-dark', 'dbt-div-coolwarm', 'dbt-div-coolwarm-dark', 'dbt-div-crimson-green', 'dbt-div-crimson-green-dark', 'dbt-div-orange-teal', 'dbt-div-orange-teal-dark', 'dbt-div-sunset', 'dbt-div-sunset-dark', 'dbt-grays', 'dbt-seq-amber', 'dbt-seq-amber-dark', 'dbt-seq-blue', 'dbt-seq-blue-dark', 'dbt-seq-brown', 'dbt-seq-brown-dark', 'dbt-seq-gray', 'dbt-seq-gray-dark', 'dbt-seq-green', 'dbt-seq-green-dark', 'dbt-seq-purple', 'dbt-seq-purple-dark', 'dbt-seq-rust', 'dbt-seq-rust-dark', 'dbt-seq-teal', 'dbt-seq-teal-dark', 'editorial-10', 'editorial-10-dark', 'editorial-10-ghost', 'editorial-10-ink', 'editorial-10-light', 'hero-6', 'info', 'negative', 'positive', 'tableau', 'vivid-10', 'vivid-10-dark', 'vivid-10-ghost', 'vivid-10-ink', 'vivid-10-light', 'warning']	✓	Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, info, negative, positive, warning, category, sequence, diverge.
roles	dict[str, str]	✓	Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading
padding	SpacingValues	✓	Per-board padding override (CSS shorthand or structured).
margin	SpacingValues	✓	Per-board margin override (CSS shorthand or structured).
gap	float	✓	Per-board gap between layout items in pixels.
color	str	✓	Per-board text color override as a CSS color string.

SingleRowBoolProbe

Single-row boolean query probe.

Field	Type	Description
query	str	Name of the query to execute.
column	str	Column in the single result row holding the boolean value.

VariableOptions

Options configuration for variable inputs.

Field	Type	Optional	Description
static	list[str | int | float]	✓	List of static option values (strings or numbers).
query	str	✓	Query name whose result rows provide option values.
column	str	✓	Column in the query result to use as option values.
label_column	str	✓	Column in the query result to use as display labels (separate from values).

FieldConditionalFormatting

Conditional formatting rules scoped to a single column.

Field	Type	Description
when	list[ConditionalRule]	Ordered list of conditional rules. The first matching rule applies; a 'default: true' rule must be last.

ChartSort

Chart-level sort configuration for categorical axes.

Field	Type	Optional	Description
by	str		Column name to sort by.
order	enum: "asc", "desc"	✓	Sort direction (asc or desc).

MultiplesConfig

Small-multiples partition, keyed by layout direction.

Field	Type	Optional	Description
rows	str	✓	Column whose distinct values become vertically stacked panel rows.
columns	str	✓	Column whose distinct values become side-by-side panel columns.
scale	enum: "shared", "independent"	✓	Measure-scale sharing across panels. 'shared' (default) makes panels visually comparable; 'independent' gives each panel its own scale.

ChartDataTable

Container for a chart's data_table block.

Field	Type	Description
entries	list[ChartDataTableSource | ChartDataTableAggregate | ChartDataTablePerSeries]	List of data-table entries (source, aggregate, or per-series rows).

BarChartStyle

Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
orientation	enum: "horizontal", "vertical", "auto"	✓	Preferred bar orientation; None uses the renderer default (vertical).
stack	enum: "none", "zero", "normalize", "center"	✓	Default stack mode for bar charts; none renders side-by-side columns.
overlap	float | enum: "auto", "none", "flush", "partial", "full"	✓	Within-group spacing for grouped bars. Keywords: 'auto' (2 series → partial, 3+ → none), 'none' (small gap), 'flush' (bars touch), 'partial' (25% overlap), 'full' (bars coincide). Or a number as a fraction of bar width: >0 overlaps, 0 touches, <0 gaps; 1 is the maximum (bars fully coincide, same as 'full') and values above 1 are clamped to 1 — bars never cross past each other. None uses the renderer default ('auto'). Only applies to grouped bars; setting it together with an active stack mode is an error.
stack_order	enum: "value", "data", "alphabetical"	✓	Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color column name. Ignored when stacking is off or no color.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for bar charts.
marks	BarChartMarksStyle	✓	Bar-family mark overrides. Unset fields fall back to style.charts.marks.

BarLayer

A bar-type layer on a cartesian chart.

Field	Type	Optional	Description
type	enum: "bar"		Bar mark layer.
query	str	✓	Query name for this layer's data (overrides chart-level query).
x	str	✓	X-axis column name for this layer.
y	str	✓	Y-axis column name for this layer.
label	str	✓	Label column name for this layer.
color	str	✓	Color data channel for this layer: bare column name only.
axis_y	LayerAxisYStyle	✓	Y-axis settings for this layer (orientation, title).
style	BarLayerStyle	✓	Bar layer mark style overrides.

LineLayer

A line-type layer on a cartesian chart.

Field	Type	Optional	Description
type	enum: "line"		Line mark layer.
query	str	✓	Query name for this layer's data (overrides chart-level query).
x	str	✓	X-axis column name for this layer.
y	str	✓	Y-axis column name for this layer.
label	str	✓	Label column name for this layer.
color	str	✓	Color data channel for this layer: bare column name only.
axis_y	LayerAxisYStyle	✓	Y-axis settings for this layer (orientation, title).
style	LineLayerStyle	✓	Line layer mark style overrides.

AreaLayer

An area-type layer on a cartesian chart.

Field	Type	Optional	Description
type	enum: "area"		Area mark layer.
query	str	✓	Query name for this layer's data (overrides chart-level query).
x	str	✓	X-axis column name for this layer.
y	str	✓	Y-axis column name for this layer.
label	str	✓	Label column name for this layer.
color	str	✓	Color data channel for this layer: bare column name only.
axis_y	LayerAxisYStyle	✓	Y-axis settings for this layer (orientation, title).
style	AreaLayerStyle	✓	Area layer mark style overrides.

ScatterLayer

A scatter-type layer on a cartesian chart.

Field	Type	Optional	Description
type	enum: "scatter"		Scatter (point) mark layer.
query	str	✓	Query name for this layer's data (overrides chart-level query).
x	str	✓	X-axis column name for this layer.
y	str	✓	Y-axis column name for this layer.
label	str	✓	Label column name for this layer.
color	str	✓	Color data channel for this layer: bare column name only.
axis_y	LayerAxisYStyle	✓	Y-axis settings for this layer (orientation, title).
style	ScatterLayerStyle	✓	Scatter layer mark style overrides.

LineChartStyle

Authored overlay for LineChartStyle. Line chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for line charts.
marks	LineChartMarksStyle	✓	Line-family mark overrides. Unset fields fall back to style.charts.marks.

AreaChartStyle

Authored overlay for AreaChartStyle. Area chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
stack	enum: "none", "zero", "normalize", "center"	✓	Default stack mode for area charts: 'none', 'zero', 'normalize', or 'center'.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for area charts.
marks	AreaChartMarksStyle	✓	Area-family mark overrides. Unset fields fall back to style.charts.marks.

ScatterChartStyle

Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
marks	ScatterChartMarksStyle	✓	Scatter-family mark overrides. Unset fields fall back to style.charts.marks.

HeatmapChartStyle

Authored overlay for HeatmapChartStyle. Heatmap chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
cell_padding	float	✓	Padding between heatmap cells in pixels.
marks	HeatmapChartMarksStyle	✓	Heatmap-family mark overrides. Unset fields fall back to style.charts.marks.

ChartTotal

Donut center total — auto-rendered sum at the center of a donut, with author override.

Field	Type	Optional	Description
visible	bool	✓	Whether to render the donut center total. Defaults True; set False to suppress the auto-rendered center on donuts whose theta values aren't a meaningful sum (e.g. pre-aggregated percentage shares).
label	str	✓	Caption text displayed below the center total value.
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format (D3 spec, preset, or FormatConfig).

PieChartStyle

Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (flat) + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Aspect ratio (width/height) of the pie chart viewport.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
inner_radius	float	✓	Hole-to-disk ratio 0–1 (inner radius / outer radius). None = solid pie (no hole).
total	TotalStyle	✓	Donut center total paint (value and label).
marks	PieChartMarksStyle	✓	Pie-family mark overrides. Unset fields fall back to style.charts.marks.

KpiSupportConfig

Support-line block authored alongside a KPI's main value.

Field	Type	Optional	Description
value	str	✓	Column reference (string column name) for the support number/text.
label	str	✓	Trailing explainer text rendered beside the support value.
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format (D3 spec, preset, or FormatConfig).
glyph	str	✓	Optional prefix glyph (e.g. '▲', '▼', '●').
tone	enum: "positive", "negative", "warning", "info"	✓	Semantic styling for the support value/glyph.

KpiChartStyle

Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.

Field	Type	Optional	Description
font	FontStyle	✓	KPI chart-level font overrides. Unset fields fall back to style.charts.font.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	KPI card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str	✓	KPI value/glyph static paint. No categorical or gradient arm — KPI has no series axis.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
value	KpiValueStyle	✓	KPI headline value slot.
label	KpiSlotStyle	✓	KPI card label slot.
affix	KpiSlotStyle	✓	Currency/percent affix slot.
glyph	KpiSlotStyle	✓	Indicator glyph (▲▼●) slot.
min_card_width	float	✓	Minimum KPI card width in pixels.
default_height	float	✓	Default KPI card height in pixels.
content_padding	SpacingValues	✓	Inner inset (top/right/bottom/left) for KPI card content in pixels.
tones	KpiTonesStyle	✓	Semantic tone color palette for the KPI support row.

TableChartStyle

Authored overlay for TableChartStyle. Table chart style overrides layered on top of shared chart defaults.

Field	Type	Optional	Description
font	FontStyle	✓	Table chart-level font overrides. Unset fields fall back to style.charts.font.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Table outer border style.
background	str	✓	Table background color; None inherits from theme.
color	StaticGradientColorStyle	✓	Table color: static text paint or gradient scale only (no categorical arm).
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
rule	TableRuleStyle	✓	Table rule style overrides (color). None = no override; inherits from theme.
outer_padding	float	✓	Outer table padding in pixels.
bottom_padding	float	✓	Extra bottom padding below the last row in pixels.
column_layout	TableColumnsStyle	✓	Default column width and cell padding settings.
header	TableHeaderStyle	✓	Table header row style.
row	TableRowStyle	✓	Table body row style.
row_numbers	TableRowNumbersStyle	✓	Leading row-number column configuration.
title_row	TableTitleStyle	✓	Table title row style.
wrap	bool	✓	Allow cell text wrapping; false clips to single line.
pagination	PaginationConfig	✓	Client-side pagination defaults for table charts.
column_defaults	TableColumnDefaultsConfig	✓	Table-level column defaults applied to every column; None means no defaults authored.
columns	dict[str, TableColumnConfig]	✓	Per-column display configuration keyed by column name (label, format, width, etc.).
header_overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Table column header text overflow mode; None inherits from theme.
paginator	PaginatorStyle	✓	Visual style for the paginator control (chevrons + page numbers).
symbol_mode	enum: "all", "anchors"	✓	Where to show currency-prefix and magnitude/unit suffix symbols in a numeric column. 'all' shows the full formatted value on every row; 'anchors' shows it only on the first data row and summary/total rows, stripping prefix and suffix from plain middle rows so the anchors guide the reader at the top and bottom of the value field.
more_rows	TableEdgeStyle	✓	Style for the 'more rows' edge-case indicator.
empty_state	TableEdgeStyle	✓	Style for the empty-state (no data) indicator.
spark	SparkStyle	✓	Inline sparkline defaults for table cells.
transpose	bool	✓	When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures.
text_baseline_offset	float	✓	Vertical offset to align SVG text baseline with cell grid in pixels.
title_subtitle_gap	float	✓	Pure whitespace between the title's descent and the subtitle's ascent, in pixels — not a baseline-to-baseline distance. Combined with the title and subtitle font sizes to reproduce Vega-Lite's title->subtitle spacing at any font size, not one calibrated pair. Font size and colour for the subtitle itself come from style.title.subtitle — the same source chart-family titles use — not a table-local constant.

BasemapConfig

Styled geographic background layer for point_map and bubble_map charts.

Field	Type	Optional	Description
source	str	✓	Named geographic boundary source (e.g. 'us-states') for overlay rendering.
fill	str	✓	Fill color for geographic boundary overlay.
stroke	str	✓	Stroke color for geographic boundary overlay.

PointMapChartStyle

Authored overlay for PointMapChartStyle. Point map chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	StaticGradientColorStyle	✓	Geo color: static paint or gradient scale only (no categorical arm).
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
projection	ProjectionStyle	✓	Vega-Lite projection configuration for this geo family.
basemap	BasemapStyle	✓	Background map layer; None source = no topo layer.
marks	PointMapChartMarksStyle	✓	Point-map-family mark overrides. Unset fields fall back to style.charts.marks.

GeoshapeChartStyle

Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	StaticGradientColorStyle	✓	Geo color: static paint or gradient scale only (no categorical arm).
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
projection	ProjectionStyle	✓	Vega-Lite projection configuration for this geo family.
basemap	BasemapStyle	✓	Background map layer; None source = no topo layer.
marks	GeoshapeChartMarksStyle	✓	Geoshape-family mark overrides. Unset fields fall back to style.charts.marks.

CalloutChartStyle

Authored overlay for CalloutChartStyle. Chart-family style for type: callout charts and runtime chart-error fallback cards.

Field	Type	Optional	Description
preferred_width	float	✓	Preferred callout width in pixels.
tone	enum: "positive", "negative", "warning", "info"	✓	Semantic tone for palette-role lookup (info | positive | negative | warning).
background	str	✓	Callout card background color (info.bg default).
border	BorderStyle	✓	Callout card border style.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
section_gap	float	✓	Vertical gap between callout title and message in pixels.
title	CalloutElementStyle	✓	Callout title element style.
message	CalloutElementStyle	✓	Callout message element style.

SparkBarChartStyle

Authored overlay for SparkBarChartStyle. Produced by cascade from theme YAML.

Field	Type	Optional	Description
preferred_width	float	✓	Preferred spark_bar chart width in pixels.
min_width	float	✓	Minimum spark_bar chart width in pixels.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
bar	SparkBarBarStyle	✓	Bar geometry (height, padding, color).
label	SparkBarChartLabelStyle	✓	Category-label column (visibility, reserved width).
count	SparkBarCountStyle	✓	Count-value column (visibility, reserved width).
max_bars	int	✓	Maximum number of bars to render.
font	FontStyle	✓	Spark_bar font style overrides. Unset fields fall back to style.charts.font.
border	BorderStyle	✓	Spark_bar outer border style.
subtitle	SubtitleStyle	✓	Spark_bar subtitle font-sizing constants.

GridItem

Grid layout item with position and span.

Field	Type	Optional	Description
item	str | Board | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart]		Chart name or inline chart/board definition to place in this grid cell.
col	int	✓	Column position (0-indexed). Auto-placed if omitted.
row	int	✓	Row position (0-indexed). Auto-placed if omitted.
col_span	int	✓	Number of columns to span (width in grid units).
row_span	int	✓	Number of rows to span (height in grid units).
width	int	✓	Alias for col_span (more intuitive name).
height	int	✓	Alias for row_span (more intuitive name).
description	str	✓	Optional metadata for AI search and context tooltips.

TabItem

Tab layout item.

Field	Type	Optional	Description
title	str		Tab label displayed in the tab bar.
icon	str	✓	Optional icon shown in the tab (e.g., emoji or icon name).
description	str	✓	Optional metadata for AI search and context tooltips.
text	str	✓	Markdown text content shown in this tab.
style	Style	✓	Style patch for this tab's content area.
rows	list[str | Board | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart]]	✓	Vertical stack layout for this tab's content.
cols	list[str | Board | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | CalloutChart | SparkBarChart]]	✓	Horizontal layout for this tab's content.
grid	GridLayout	✓	CSS-grid layout for this tab's content.
tabs	TabLayout	✓	Nested tab layout (tabs within tabs).

FrameStyle

Authored overlay for FrameStyle. Board-level structural dimensions. Do NOT cascade to child boards.

Field	Type	Optional	Description
width	float	✓	Maximum board width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dct HTML page (dct serve, dct render --format html), which scales the board to its container.
min_height	float	✓	Minimum board height in pixels.
margin	float	✓	Board outer margin in pixels.
card_padding	float	✓	Padding added to each card side in pixels.
card_gap	float	✓	Gap between cards in pixels.

RootFontStyle

Authored overlay for RootFontStyle. Root-level font configuration: FontStyle fields plus a required emoji mode.

Field	Type	Optional	Description
family	str	✓	Font family name (e.g., 'sans-serif', 'Roboto').
color	str	✓	Text color as a CSS color string.
size	float	✓	Font size in pixels.
weight	str | float	✓	Font weight (e.g., 'bold', 400, 700).
style	enum: "normal", "italic"	✓	Font style (normal or italic).
decoration	enum: "none", "line-through", "underline"	✓	Text decoration (underline, line-through, or none).
case	enum: "none", "sentence", "title", "upper", "lower", "slug", "camel"	✓	Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change.
line_height	float	✓	Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML.
emoji	enum: "monochrome", "system-default", "disabled"	✓	Emoji rendering mode for the dashboard font stack.

BorderStyle

Box border. Does NOT cascade (ADR-003: box properties reset per level).

Field	Type	Optional	Description
radius	float	✓	Border corner radius in pixels.
color	str	✓	Border color (CSS color string).
width	float	✓	Border width in pixels.
dash_array	list[float]	✓	SVG stroke-dasharray pattern in pixels (e.g. [4, 4]). None means a solid border.
line_cap	enum: "butt", "round", "square"	✓	SVG stroke-linecap for a dashed border. None uses the renderer default (butt).
dash_offset	float	✓	SVG stroke-dashoffset in pixels. None means 0.

TitleStyle

Authored overlay for TitleStyle. Board and board titles.

Field	Type	Optional	Description
font	FontStyle	✓	Title font style overrides. Unset fields fall back to style.font.
compact_weight	str | float	✓	Object-title font weight on tiny cards.
sizes	list[float]	✓	Font sizes for the H1–H6 heading ramp, indexed by board.level - 1. Board/prose titles index this ramp directly (no width input). Object titles (chart/table/spark) combine width_offsets with a fixed object-title anchor to pick a slot.
width_offsets	TitleWidthOffsetsStyle	✓	Additive level offsets by card width (tiny/narrow/medium/wide). Object titles add the tier offset to a fixed anchor to pick an H slot from sizes. Board/prose titles are level-only and do not consult these.
min_height	float	✓	Minimum title row height in pixels.
overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Text overflow mode (clip, truncate, wrap-two, wrap).
position	TitlePositionStyle	✓	Vega-Lite title positioning: anchor, angle, offset, baseline.
level	int | enum: "auto"	✓	Heading level override for board titles. 'auto' (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this board and its descendants to that H-level.
subtitle	TitleSubtitleStyle	✓	Subtitle font styles.

TextStyle

Authored overlay for TextStyle. Markdown / plain text content.

Field	Type	Optional	Description
font	FontStyle	✓	Text font style overrides. Unset fields fall back to style.font.
align	enum: "left", "center", "right"	✓	Text alignment for the board body-text block.
paragraph	BlockMarginStyle	✓	Spacing above/below each paragraph block (in line-height units).
heading	BlockMarginStyle	✓	Spacing above/below heading blocks (H1–H6) in line-height units.
column	TextColumnStyle	✓	Multi-column layout for the board body-text block.
code	TextCodeStyle	✓	Inline + fenced code box styling (font, background, border).
blockquote	TextBlockquoteStyle	✓	Blockquote box styling (font, background, border/left-rule).
bold	TextBoldStyle	✓	Inline bold-run styling (weight), distinct from heading weight.

PlaceholderStyle

Authored overlay for PlaceholderStyle.

Field	Type	Optional	Description
opacity	float	✓	Opacity of the placeholder overlay (0–1).
overlay	PlaceholderOverlay	✓	Overlay text and background style.

ChartsStyle

Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared chart configuration.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides. Unset fields fall back to style.font.
preferred_width	float	✓	Preferred chart width in pixels.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart canvas background; None inherits from the board background via apply_inherit. Falls back to style.background.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height).
min_height	float	✓	Minimum chart height in pixels.
max_height	float	✓	Maximum chart height in pixels.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Board-wide chart tooltip style.
dashes	list[list[int]]	✓	Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission.
default_chart_height	float	✓	Fallback chart height in pixels when aspect-ratio sizing is unavailable.
default_table_height	float	✓	Placeholder table height in pixels; replaced by data-aware row-count sizing at render time.
label_usable_ratio	float	✓	Fraction of chart width usable for axis labels (0–1); labels are tilted when full labels exceed this width.
axis	BaseAxisStyle	✓	Shared axis style applied to all axes before per-axis overrides.
axis_x	AxisXStyle	✓	X-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis.
axis_y	AxisYStyle	✓	Y-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis.
axis_quantitative	QuantitativeAxisStyle	✓	Quantitative axis style overrides applied after axis_x/axis_y. Unset fields fall back to style.charts.axis.
view	ViewStyle	✓	Vega-Lite view dimensions and border.
marks	GlobalMarksStyle	✓	Global mark defaults (tier-1 of the marks cascade).
bar	BarChartStyle	✓	Bar chart style.
line	LineChartStyle	✓	Line chart style.
area	AreaChartStyle	✓	Area chart style.
scatter	ScatterChartStyle	✓	Scatter chart style.
histogram	HistogramChartStyle	✓	Histogram chart style.
heatmap	HeatmapChartStyle	✓	Heatmap chart style.
geoshape	GeoshapeChartStyle	✓	Geoshape (choropleth) chart style.
point_map	PointMapChartStyle	✓	Point map chart style.
pie	PieChartStyle	✓	Pie/donut chart style.
series_label	SeriesLabelStyle	✓	Shared series-label typography for endpoint and stack labels.
kpi	KpiChartStyle	✓	KPI card chart style.
table	TableChartStyle	✓	Table chart style.
spark_bar	SparkBarChartStyle	✓	Spark_bar (full-chart horizontal bar) style.
data_table	DataTableStyle	✓	Attached data_table strip style.
callout	CalloutChartStyle	✓	Callout chart-family style for type:callout and runtime fallback cards.

LayoutStyle

Authored overlay for LayoutStyle.

Field	Type	Optional	Description
rows	LayoutGapStyle	✓	Row layout gap configuration.
cols	LayoutGapStyle	✓	Column layout gap configuration.
grid	GridLayoutStyle	✓	Grid layout configuration.
tabs	TabsStyle	✓	Tabs layout style.
details	DetailsStyle	✓	Details (accordion) layout style.

VariablesStyle

Authored overlay for VariablesStyle. Variable controls chrome styling.

Field	Type	Optional	Description
visible	bool	✓	Show the variables control panel.
position	enum: "top", "bottom", "title-inline"	✓	Variables strip placement: stacked under the title (top/bottom) or on one horizontal band with the board title (title-inline).
title_inline_band_bottom_pad	float	✓	Bottom padding in pixels added below the title-inline band.
gap	float	✓	Gap between variable controls in pixels.
label_position	str	✓	Position of labels relative to their input controls (e.g. 'left', 'top').
title_inline_title_max_width	float	✓	When position is title-inline: max title column width in px. 0 means no cap (title uses remaining width after reserving space for variables).
font	FontStyle	✓	Variables panel base font style overrides. Unset fields fall back to style.font.
label	VariablesLabelStyle	✓	Variable label typography.
value	VariablesValueStyle	✓	Variable value typography.
placeholder	VariablesPlaceholderStyle	✓	Style for unselected/hint text in variable inputs.
container_height	float	✓	Height of the variables panel container in pixels.
border	BorderStyle	✓	Variables panel border style.
control_gap	float	✓	Gap between label and input within a single control in pixels.
input	InputStyle	✓	Input control style.

PageStyle

Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.

Field	Type	Optional	Description
background	str	✓	Page canvas background color (behind the board).

FooterStyle

Authored overlay for FooterStyle. Page footer chrome: visibility, attribution text, font, and rule.

Field	Type	Optional	Description
visible	bool	✓	Show the footer attribution line.
text	str	✓	Attribution text shown in the footer.
link	str	✓	URL the footer brand phrase 'dbt charts' links to; null renders plain text.
font	FontStyle	✓	Footer text font style (size and color required).
y_offset	float	✓	Vertical offset from bottom edge in pixels.
rule	FooterRule	✓	Hairline rule above footer text; null disables the rule.

TimestampStyle

Authored overlay for TimestampStyle. Authored data-freshness chrome: visibility, placement, strftime format, font, and y-offset.

Field	Type	Optional	Description
visible	bool	✓	Show the data-freshness line.
position	enum: "top", "footer"	✓	Timestamp row: top page chrome or footer baseline.
align	enum: "left", "right"	✓	Timestamp horizontal alignment within its row.
format	str	✓	strftime format for the data-freshness line, including any literal label text (e.g. '%H:%M %Z on %-d %b %Y'). The value is always UTC; a format that prints a clock must disclose the zone (%Z or a literal 'UTC'), else compile rejects it — an unlabeled clock reads as local.
y	float	✓	Y-coordinate for top-positioned timestamp in pixels.
font	FontStyle	✓	Timestamp font style overrides (size, color, weight, ...).

SpacingValues

Pre-parsed CSS spacing (margin/padding).

Field	Type	Optional	Description
top	float	✓	Top spacing in pixels.
right	float	✓	Right spacing in pixels.
bottom	float	✓	Bottom spacing in pixels.
left	float	✓	Left spacing in pixels.

ConditionalRule

A single conditional formatting rule.

Field	Type	Optional	Description
eq	Any	✓	Match rows where the column value equals this value.
ne	Any	✓	Match rows where the column value does not equal this value.
lt	int | float	✓	Match rows where the column value is less than this number.
lte	int | float	✓	Match rows where the column value is less than or equal to this number.
gt	int | float	✓	Match rows where the column value is greater than this number.
gte	int | float	✓	Match rows where the column value is greater than or equal to this number.
between	list[int | float]	✓	Match rows where the column value falls in [low, high] (inclusive).
in	list[Any]	✓	Match rows where the column value is in this list.
is_null	bool	✓	Match null rows (true) or non-null rows (false).
default	enum: "True"	✓	Catch-all rule that matches any row not matched by earlier rules. Must be the last entry.
background	str	✓	Cell background color applied when the rule matches.
font	FontStyle	✓	Font style overrides (color, weight, style, decoration) applied when the rule matches.
glyph	str	✓	Glyph character prepended to the cell value when the rule matches.
glyph_color	str	✓	Color for the glyph when the rule matches. Requires glyph to be set.
tone	enum: "positive", "negative", "warning", "info"	✓	Semantic tone (positive|negative|warning|info) that colors the glyph via the theme's tone palette — the preferred, theme-adaptive alternative to a raw glyph_color. Requires glyph. Explicit glyph_color wins.

ChartDataTableSource

A data_table row that reads a column's raw per-x value.

Field	Type	Optional	Description
source	str		Query column the row reads from (per-x raw value).
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	D3 format string or format config object. Optional; inherits the chart measure format when omitted and source matches chart.y.
label	str	✓	Left-stub row label. Optional.

ChartDataTableAggregate

A data_table row that reads an aggregate of a column grouped by x.

Field	Type	Optional	Description
aggregate	enum: "sum", "avg", "min", "max", "median", "count", "count_distinct"		Aggregate operation applied per x-group. One of: sum, avg, min, max, median, count, count_distinct. Exact names only — no aliases (spec G4).
source	str		Query column being aggregated. Always required alongside aggregate: (spec G2).
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	D3 format string or format config object for the aggregated value. Optional.
label	str	✓	Column header label override for this row.

ChartDataTablePerSeries

A data_table entry that expands into one row per color: series.

Field	Type	Optional	Description
per_series	str		Query column the row reads from (per-x, per-series value).
by_measure	bool	✓	When True, expand one row reading the named measure field directly (no color: groupby). Required for multi-y charts where each measure is its own y-field rather than a color-encoded series.
label	str	✓	Row label displayed in the strip's label gutter. When None and by_measure=True, the per_series column name is used. Has no effect when by_measure=False (series name is the label).
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	D3 format string or format config object. Optional.

FontStyle

Text appearance. Merged as a unit.

Field	Type	Optional	Description
family	str	✓	Font family name (e.g., 'sans-serif', 'Roboto').
color	str	✓	Text color as a CSS color string.
size	float	✓	Font size in pixels.
weight	str | float	✓	Font weight (e.g., 'bold', 400, 700).
style	enum: "normal", "italic"	✓	Font style (normal or italic).
decoration	enum: "none", "line-through", "underline"	✓	Text decoration (underline, line-through, or none).
case	enum: "none", "sentence", "title", "upper", "lower", "slug", "camel"	✓	Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change.
line_height	float	✓	Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML.

PaddingStyle

Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides required; theme YAML supplies defaults.

Field	Type	Optional	Description
left	float	✓	Left padding in pixels.
right	float	✓	Right padding in pixels.
top	float	✓	Top padding in pixels.
bottom	float	✓	Bottom padding in pixels.

ColorStyle

Authored overlay for ColorStyle. Unified chart color config: static paint, categorical palette, gradient scale.

Field	Type	Optional	Description
static	str	✓	Static mark color override.
gradient	ScaleTargetConfig	✓	Continuous gradient scale for the color encoding.
categorical	CategoricalColorStyle	✓	Categorical color and single-series palette config.

LegendStyle

Authored overlay for LegendStyle.

Field	Type	Optional	Description
position	enum: "none", "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"	✓	Legend position (VL legend orient).
direction	enum: "horizontal", "vertical"	✓	Legend layout direction.
columns	int	✓	Legend entry columns. Zero keeps the renderer default; positive values set Vega-Lite legend columns.
compact_columns	int	✓	Entry columns for an automatic compact top-horizontal legend.
label	LegendLabelStyle	✓	Legend label style.
title	LegendTitleStyle	✓	Legend title style.
visible	bool	✓	Show the legend. None = legend visible; False = explicitly suppressed.
symbol_limit	int	✓	Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series.
values	list[str]	✓	Explicit legend entry order/filter; maps to VL legend.values. None lets the renderer infer order from the data.
symbol_shape	str	✓	Override the legend glyph shape; maps to VL legend.symbolType. None uses the mark-aware glyph derived from the chart's mark type.
symbol_fill	bool	✓	When False, emits symbolFillColor='transparent' to produce a hollow legend glyph. None uses Vega-Lite's default (filled symbol).

BaseAxisStyle

Authored overlay for BaseAxisStyle. Universal axis surface — grid/line/ticks/labels/title/scale.

Field	Type	Optional	Description
grid	BaseAxisGridStyle	✓	Grid line style for this axis.
line	AxisLineStyle	✓	Domain line style for this axis.
ticks	AxisTicksStyle	✓	Tick mark style for this axis.
labels	AxisLabelStyle	✓	Axis label style.
title	AxisTitleStyle	✓	Axis title style.
scale	BaseScaleStyle	✓	Per-axis scale overrides; None means no override.

AxisXStyle

Authored overlay for AxisXStyle. Dimension/category-time axis style. Theme slot: axis_x.

Field	Type	Optional	Description
grid	BaseAxisGridStyle	✓	Grid line style for this axis.
line	AxisLineStyle	✓	Domain line style for this axis.
ticks	DimensionTicksStyle	✓	Dimension axis tick style.
labels	DimensionLabelStyle	✓	Dimension axis label style.
title	AxisTitleStyle	✓	Axis title style.
scale	XScaleStyle	✓	X-axis scale overrides including x_reverse; None means no override.
position	enum: "top", "bottom"	✓	X-axis position; None uses Vega-Lite's default (bottom).
time_unit	enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none"	✓	Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data.
type	enum: "auto", "ordinal", "temporal"	✓	Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain.
fill	enum: "null", "zero", "linear", "step-after", "step-before", "step-center", "curve"	✓	Fill for synthesized missing-bucket rows: null, zero, linear, step-after / step-before / step-center (Looker step), or curve (smoothstep).
fiscal_year_start_month	int	✓	Calendar month (1=Jan..12=Dec) that opens a fiscal year/quarter for year/yearquarter bucketing; theme default 1 is the calendar convention (Q1=Jan-Mar). A non-default value always wins over axis_x.type: temporal for year/yearquarter grains - Vega-Lite's native timeUnit transform has no fiscal-offset concept and would otherwise silently discard the offset.

AxisYStyle

Authored overlay for AxisYStyle. Measure axis style. Theme slot: axis_y.

Field	Type	Optional	Description
grid	MeasureGridStyle	✓	Measure axis grid style (includes zero-baseline override).
line	AxisLineStyle	✓	Domain line style for this axis.
ticks	AxisTicksStyle	✓	Tick mark style for this axis.
labels	AxisLabelStyle	✓	Axis label style.
title	AxisTitleStyle	✓	Axis title style.
scale	BaseScaleStyle	✓	Per-axis scale overrides; None means no override.
position	enum: "left", "right", "auto"	✓	Y-axis position; auto flips when endpoint labels are on the right.
mirror	bool | AxisMirrorStyle	✓	Draw the y-scale on both left and right edges (wide charts). true mirrors the primary axis's label verbatim; an object (format/expr) relabels only the mirrored edge — e.g. a percent-of-total right axis next to an absolute-value left axis — while ticks stay aligned to the single shared scale. Only meaningful on axis_y.

QuantitativeAxisStyle

Authored overlay for QuantitativeAxisStyle. Scale-type overlay for quantitative axes. Theme slot: axis_quantitative.

Field	Type	Optional	Description
grid	BaseAxisGridStyle	✓	Grid line style for this axis.
line	AxisLineStyle	✓	Domain line style for this axis.
ticks	AxisTicksStyle	✓	Tick mark style for this axis.
labels	AxisLabelStyle	✓	Axis label style.
title	AxisTitleStyle	✓	Axis title style.
scale	BaseScaleStyle	✓	Per-axis scale overrides; None means no override.

BandAxisStyle

Authored overlay for BandAxisStyle. Scale-type overlay for band (categorical) axes. Theme slot: axis_band.

Field	Type	Optional	Description
grid	BaseAxisGridStyle	✓	Grid line style for this axis.
line	AxisLineStyle	✓	Domain line style for this axis.
ticks	AxisTicksStyle	✓	Tick mark style for this axis.
labels	AxisLabelStyle	✓	Axis label style.
title	AxisTitleStyle	✓	Axis title style.
scale	BaseScaleStyle	✓	Per-axis scale overrides; None means no override.
band_position	float	✓	Band position within the step (0–1); None uses Vega-Lite's default.

DataTableStyle

Authored overlay for DataTableStyle. Attached data_table style. Lives at style.charts.data_table.*.

Field	Type	Optional	Description
font	FontStyle	✓	Data_table font style overrides. Unset fields fall back to style.charts.font.
divider	RuleStyle	✓	Rule at the boundary between the chart plot and the data strip. For position='bottom': rule sits above the strip (below the axis). For position='top': rule sits below the strip rows (above the plot top).
row	DataTableRowStyle	✓	Data_table row padding and rule style.
label	DataTableLabelStyle	✓	Row label (series name) style.
padding_top	float	✓	Padding above the topmost strip row in pixels. For position='bottom': gap between axis labels and the first row. For position='top': space above the topmost row (outer edge of strip).
padding_bottom	float	✓	Padding below the last strip row in pixels. For position='bottom': space below the last row. For position='top': gap between the last row and the plot top edge.
label_max_lines	int	✓	Number of x-axis label lines to reserve in the axis gap (only used for position='bottom'; ignored for position='top'). Typically 1 or 2.
position	enum: "top", "bottom"	✓	Strip placement relative to the chart plot. 'top' places the strip above the plot (no x-axis gap needed); 'bottom' places it below with the x-axis between plot and strip.

EndpointLabelsConfig

Authored overlay for EndpointLabelsConfig. Endpoint label pane config — shared across line, area, and bar.

Field	Type	Optional	Description
visible	bool	✓	Show endpoint labels; theme sets false, authors opt in per chart.
label_offset	float	✓	Spacing in pixels between the chart pane and the label pane.
height	float	✓	Height in pixels of the endpoint-label pane (top_rail layout).

BarChartMarksStyle

Authored overlay for BarChartMarksStyle. Bar-family mark overrides. Only bar and text (endpoint labels) are valid.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Bar mark overrides for bar charts; inherits from global.
text	TextMarkStyle	✓	Text mark overrides for bar endpoint labels; inherits from global.

LayerAxisYStyle

Per-layer y-axis settings on a layered chart.

Field	Type	Optional	Description
position	enum: "left", "right"	✓	Y-axis side for this layer (left or right).
title	str	✓	Y-axis title override for this layer.
scale	LayerAxisYScale	✓	Scale overrides for this layer's y axis.
ticks	LayerAxisYTicks	✓	Tick overrides for this layer's y axis.
grid	LayerAxisYGrid	✓	Grid overrides for this layer's y axis.
label	LayerAxisYLabel	✓	Label format override for this layer's y axis.

BarLayerStyle

Authored overlay for BarLayerStyle. Required wrapper for bar-layer mark overrides (built into a Patch by build_patch_model).

Field	Type	Optional	Description
marks	BarChartMarksStyle	✓	Mark overrides for this bar layer.

LineLayerStyle

Authored overlay for LineLayerStyle. Required wrapper for line-layer mark overrides (built into a Patch by build_patch_model).

Field	Type	Optional	Description
marks	LineChartMarksStyle	✓	Mark overrides for this line layer.

AreaLayerStyle

Authored overlay for AreaLayerStyle. Required wrapper for area-layer mark overrides (built into a Patch by build_patch_model).

Field	Type	Optional	Description
marks	AreaChartMarksStyle	✓	Mark overrides for this area layer.

ScatterLayerStyle

Authored overlay for ScatterLayerStyle. Required wrapper for scatter-layer mark overrides (built into a Patch by build_patch_model).

Field	Type	Optional	Description
marks	ScatterChartMarksStyle	✓	Mark overrides for this scatter layer.

LineChartMarksStyle

Authored overlay for LineChartMarksStyle. Line-family mark overrides.

Field	Type	Optional	Description
line	LineMarkStyle	✓	Line mark overrides; inherits from global.
point	PointMarkStyle	✓	Point mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; inherits from global.
rule	RuleMarkStyle	✓	Rule mark overrides; None inherits global.

AreaChartMarksStyle

Authored overlay for AreaChartMarksStyle. Area-family mark overrides.

Field	Type	Optional	Description
area	AreaMarkStyle	✓	Area fill mark overrides; inherits from global.
line	AreaLineStyle	✓	Top-edge line stroke/halo/label overrides; inherits from global.
point	PointMarkStyle	✓	Point-overlay mark overrides; inherits from global.

ScatterChartMarksStyle

Authored overlay for ScatterChartMarksStyle. Scatter-family mark overrides.

Field	Type	Optional	Description
point	PointMarkStyle	✓	Point mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; inherits from global.

HeatmapChartMarksStyle

Authored overlay for HeatmapChartMarksStyle. Heatmap-family mark overrides.

Field	Type	Optional	Description
rect	RectMarkStyle	✓	Rect mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; None inherits global.

FormatConfig

Format configuration for value display.

Field	Type	Optional	Description
spec	str	✓	D3 format string (e.g., ',.0f'), preset name (e.g., 'currency'), or Excel pattern.
prefix	str	✓	Custom prefix prepended to the formatted value (e.g., '$').
suffix	str	✓	Custom suffix appended to the formatted value (e.g., ' USD', '%').
notation	enum: "analytic", "narrative"	✓	Notation style: 'analytic' for SI-prefix (1 B, 1 M) or 'narrative' for prose-style (1bn, 1mn).

TotalStyle

Authored overlay for TotalStyle. Donut center total paint: value (the number) and label (the caption).

Field	Type	Optional	Description
value	TotalSlotStyle	✓	Style for the donut center value (the number).
label	TotalSlotStyle	✓	Style for the donut center label (the caption).

PieChartMarksStyle

Authored overlay for PieChartMarksStyle. Pie/donut-family mark overrides.

Field	Type	Optional	Description
slice	SliceMarkStyle	✓	Slice mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; None inherits global.

KpiValueStyle

Authored overlay for KpiValueStyle. KPI headline value slot: font and format. Theme populates font.size directly.

Field	Type	Optional	Description
font	FontStyle	✓	KPI value font style. Unset fields fall back to style.charts.kpi.font.
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format for the KPI headline value: D3 format string, preset name, or FormatConfig object.

KpiSlotStyle

Authored overlay for KpiSlotStyle. KPI per-slot style for label, affix, and glyph slots.

Field	Type	Optional	Description
font	FontStyle	✓	Slot font style. Unset fields fall back to style.charts.kpi.font.
character	str	✓	Glyph character to render (e.g. '▲'). None = no glyph.

KpiTonesStyle

Authored overlay for KpiTonesStyle. Semantic tone palette for the KPI support row and table conditional glyphs.

Field	Type	Optional	Description
positive	str	✓	Color for positive/good tone indicators.
negative	str	✓	Color for negative/bad tone indicators.
warning	str	✓	Color for warning/caution tone indicators.
info	str	✓	Color for neutral/informational tone indicators.

StaticGradientColorStyle

Authored overlay for StaticGradientColorStyle. Color config for geo/point_map/table families — no categorical arm.

Field	Type	Optional	Description
static	str	✓	Static mark color override.
gradient	ScaleTargetConfig	✓	Continuous gradient scale for the color encoding.

TableRuleStyle

Authored overlay for TableRuleStyle. Table rule color override block.

Field	Type	Optional	Description
color	str	✓	Table rule color; None uses the theme default.

TableColumnsStyle

Authored overlay for TableColumnsStyle.

Field	Type	Optional	Description
default_width	float	✓	Default column width in pixels.
cell_padding	float	✓	Horizontal padding inside table cells in pixels.
width_similarity_threshold	float	✓	Auto-width columns whose min/max ratio >= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width.
content_headroom	float	✓	Fractional breathing room added above the raw p95 column demand when pinning compact columns in mixed (compact + text) tables. 0.10 means each compact column is pinned at 10 % above its measured demand; the extra width is funded by the text-column budget. Has no effect on all-compact tables (proportional scaling already fills the budget). 0.0 disables headroom.

TableHeaderStyle

Authored overlay for TableHeaderStyle.

Field	Type	Optional	Description
visible	bool	✓	Show the header row (column labels + rule). Set to False on series-keyed tables where column meanings are obvious from context (e.g. donut-attached tables: swatch / share / name / value). Theme YAML supplies the UX default (true) via _base.yaml.
height	float	✓	Header row height in pixels.
font	FontStyle	✓	Header font style overrides. Unset fields fall back to style.charts.table.font.
font_compact	FontStyle	✓	Compact-tier font overrides applied when body size ≤11px; None means no compact override.
background	str	✓	Header background color; None means no fill (rule alone separates header from body).
overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Header text overflow mode (clip, truncate, wrap-two, wrap).
rule	RuleStyle	✓	Header bottom rule style.

TableRowStyle

Authored overlay for TableRowStyle.

Field	Type	Optional	Description
height	float	✓	Body row height in pixels.
stripe	TableRowStripeStyle	✓	Alternating row stripe style; None means no stripe.
rule	RuleStyle	✓	Row bottom rule style.
role	str	✓	Default row role assignment; None means plain body row.
roles	TableRowRolesStyle	✓	Per-role style overrides for summary and total rows.

TableRowNumbersStyle

Authored overlay for TableRowNumbersStyle. Leading row-number column (style.table.row_numbers).

Field	Type	Optional	Description
visible	bool	✓	Show a leading row-number column; false by default.
header	str	✓	Header label for the row-number column.
align	enum: "left", "right"	✓	Text alignment for the row-number column.

TableTitleStyle

Authored overlay for TableTitleStyle.

Field	Type	Optional	Description
height	float	✓	Minimum title-block height in pixels. Applies as a floor only when a subtitle is present; a title-only block sizes to its natural content height instead.
font	FontStyle	✓	Table title font style overrides. Unset fields fall back to style.charts.table.font.

PaginationConfig

Table pagination configuration.

Field	Type	Optional	Description
enabled	bool	✓	Enable client-side pagination for table charts.
page_rows	int	✓	Rows per page. When enabled and None, the renderer auto-fits page size to the cell — set explicitly to pin the page size.

TableColumnDefaultsConfig

Table-level defaults applied to every column unless overridden per-column.

Field	Type	Optional	Description
label	str	✓	Override column header label text.
width	int | str	✓	Override column width in pixels (integer) or a CSS width string.
align	enum: "left", "center", "right"	✓	Override cell text alignment (left, center, or right).
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Override cell value format (D3 format string or format config object).
background	str	✓	Override cell background color (CSS color string).
font	FontStyle	✓	Override cell font style (size, weight, color, family).

TableColumnConfig

Configuration for a single table column.

Field	Type	Optional	Description
label	str	✓	Display header label (defaults to column name).
format	str | FormatConfig | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format (D3 string, preset name, or FormatConfig).
spark	SparkConfig | enum: "line", "area", "bar", "bar-normalize", "column", "columns"	✓	Inline spark chart config or spark type name.
swatch	bool	✓	When True, render this column's cells as small rounded color squares instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). Useful for series-keyed tables — e.g. a 'Series' column where each row is identified by its color in the parent chart's palette.
width	int | str	✓	Column width (integer pixels or CSS string like '10%').
max_width	int | str	✓	Maximum column width for auto-sized text columns (integer pixels or CSS string like '30%'). Cannot be set together with width:.
align	enum: "left", "center", "right"	✓	Text alignment in cells (left, center, right).
header_overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Header text overflow mode (clip, truncate, wrap-two, wrap).
header_link	str	✓	URL template for the column header link.
link	str	✓	URL template for cell values (Jinja template with row fields available).
background	str	✓	Cell background color (hex string, or 'transparent'/'none'), or a column ID — a value matching a query column name uses that row's value in the named column instead of the literal string.
font	FontStyle	✓	Cell font style overrides. color and weight resolve column-ID-first, the same as background — a value matching a query column name uses that row's value in the named column.
scale	ColumnScaleConfig	✓	Continuous color mapping configuration for this column.
glyph	str	✓	Glyph character prepended to cell values.
glyph_color	str	✓	Color for the glyph. Requires glyph to be set.

PaginatorStyle

Authored overlay for PaginatorStyle. Visual style for the paginator control (chevrons + page numbers).

Field	Type	Optional	Description
color_active	str	✓	Current page and live chevron color (theme body ink).
color_inactive	str	✓	Other pages and ellipsis color (theme secondary text).
color_disabled	str	✓	Chevron color when at first/last page (signals disabled by tone).
font	FontStyle	✓	Paginator font overrides (size, family).
weight_active	int	✓	Font weight for the current (selected) page number.
weight_inactive	int	✓	Font weight for other pages and ellipsis.
weight_chevron	int	✓	Font weight for the prev/next chevrons (live and disabled). Usually heavier than weight_active so the chevrons read as interactive affordances against the lighter page numbers.
item_width	float	✓	Per-item slot width in pixels (drives layout step).

TableEdgeStyle

Authored overlay for TableEdgeStyle. more_rows or empty_state edge-case UI.

Field	Type	Optional	Description
font	FontStyle	✓	Edge-case UI (more_rows / empty_state) font style overrides. Unset fields fall back to style.charts.table.font.

SparkStyle

Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).

Field	Type	Optional	Description
color	str	✓	Sparkline line/point color; None seeds from style.charts.color.categorical.single_series_palette[0].
padding	SpacingValues	✓	Cell padding around the sparkline in pixels.
empty	SparkEmptyStyle	✓	Style for empty/no-data sparklines.
single_value	SparkSingleValueStyle	✓	Style for single-data-point sparklines.
columns	SparkColumnsStyle	✓	Style for column-type sparklines.
column	SparkColumnStyle	✓	Style for the single vertical column spark mark.
bar	SparkBarCellStyle	✓	Style for bar/bar-normalize sparklines.
area	SparkAreaStyle	✓	Style for area sparklines.

ProjectionStyle

Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.

Field	Type	Optional	Description
type	str	✓	Vega-Lite projection type (e.g. 'mercator', 'albersUsa', 'equalEarth').

BasemapStyle

Authored overlay for BasemapStyle. Background map layer for geo charts (especially point maps).

Field	Type	Optional	Description
source	str	✓	Background topo source identifier; None means no base layer.

PointMapChartMarksStyle

Authored overlay for PointMapChartMarksStyle. Point map-family mark overrides.

Field	Type	Optional	Description
point	PointMarkStyle	✓	Point mark overrides; inherits from global.

GeoshapeChartMarksStyle

Authored overlay for GeoshapeChartMarksStyle. Geoshape-family mark overrides.

Field	Type	Optional	Description
geoshape	GeoshapeMarkStyle	✓	Geoshape mark overrides; inherits from global.

CalloutElementStyle

Authored overlay for CalloutElementStyle. Font + y_offset for a callout title or message.

Field	Type	Optional	Description
font	FontStyle	✓	Element font style overrides. Unset fields fall back to style.charts.font.
y_offset	float	✓	Vertical offset from the element's anchor in pixels.

SparkBarBarStyle

Authored overlay for SparkBarBarStyle. Bar geometry sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
height	float	✓	Height of each bar in pixels.
padding	float	✓	Vertical padding between bars in pixels.
color	str	✓	Bar fill color; None seeds from style.charts.color.categorical.single_series_palette[0].
background	str	✓	Bar track background color - fill-grade, pinned per theme.

SparkBarChartLabelStyle

Authored overlay for SparkBarChartLabelStyle. Category-label sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
visible	bool	✓	Show series label text next to bars.
width	float	✓	Reserved width for bar label text in pixels.

SparkBarCountStyle

Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
visible	bool	✓	Show count/value text next to bars.
width	float	✓	Reserved width for bar count text in pixels.

SubtitleStyle

Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).

Field	Type	Optional	Description
font	FontStyle	✓	Subtitle font style; theme populates font.size directly.

TitleWidthOffsetsStyle

Authored overlay for TitleWidthOffsetsStyle. Additive level offsets applied to a board/chart title's heading level, by card pixel width.

Field	Type	Optional	Description
tiny	int	✓	Level offset for the tiny tier (cards narrower than ~360px).
narrow	int	✓	Level offset for the narrow tier (cards ~360–559px).
medium	int	✓	Level offset for the medium tier (cards ~560–1099px).
wide	int	✓	Level offset for the wide tier (cards ~1100px and up).

TitlePositionStyle

Authored overlay for TitlePositionStyle. Vega-Lite title positioning pass-throughs grouped as a sub-object.

Field	Type	Optional	Description
anchor	str	✓	Title anchor position; theme always sets this.
angle	float	✓	Title rotation angle in degrees; None lets Vega-Lite choose.
offset	float	✓	Title offset from its anchor in pixels; None uses Vega-Lite's default.
baseline	str	✓	Title text baseline alignment; None uses Vega-Lite's default.

TitleSubtitleStyle

Authored overlay for TitleSubtitleStyle. VL subtitle font pass-through, grouped for consistency with TitleStyle.font.

Field	Type	Optional	Description
font	FontStyle	✓	Subtitle font style overrides (color, family, size, weight). Unset fields fall back to style.font.
overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Text overflow mode for the subtitle (clip, truncate, wrap-two, wrap). None means not set at this cascade level (theme floor is wrap-two).

BlockMarginStyle

Authored overlay for BlockMarginStyle. Top and bottom margin for a prose block role, in line-height units.

Field	Type	Optional	Description
margin_top	float	✓	Space above the block, in line-height units (lh × font_size × value).
margin_bottom	float	✓	Space below the block, in line-height units (lh × font_size × value).

TextColumnStyle

Authored overlay for TextColumnStyle. Author overrides for the column layout of board body text.

Field	Type	Optional	Description
max_number	int	✓	Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling.
gap	float	✓	Gap between columns in pixels. None = 1.5 line boxes, so the gutter scales with the type it separates.
rule	ColumnRuleStyle	✓	Vertical rule drawn between columns. None = no rule.
max_chars	int	✓	Column width as a character count, overriding the shipped measure. The width is used exactly and the column count follows from it.

TextCodeStyle

Authored overlay for TextCodeStyle. Inline and fenced code spans in markdown prose. Box group; mono font by default.

Field	Type	Optional	Description
font	FontStyle	✓	Box text font overrides — full FontStyle (family, color, size, weight, style, decoration, case).
background	str	✓	Box background fill.
border	BorderStyle	✓	Box border (width, color, radius).
highlight	bool	✓	Syntax-highlight fenced markdown code blocks.
theme	str	✓	Pygments style name for fenced markdown code tokens.

TextBlockquoteStyle

Authored overlay for TextBlockquoteStyle. Blockquote prose. Box group; border is the left rule.

Field	Type	Optional	Description
font	FontStyle	✓	Box text font overrides — full FontStyle (family, color, size, weight, style, decoration, case).
background	str	✓	Box background fill.
border	BorderStyle	✓	Box border (width, color, radius).

TextBoldStyle

Authored overlay for TextBoldStyle. Inline bold text runs in markdown prose, distinct from heading weight.

Field	Type	Optional	Description
weight	str | float	✓	CSS font-weight for bold text runs and bold table cells.

PlaceholderOverlay

Authored overlay for PlaceholderOverlay.

Field	Type	Optional	Description
text	str	✓	Placeholder overlay text shown on empty charts.
background	str	✓	Overlay background color.
font	FontStyle	✓	Overlay font style overrides. Unset fields fall back to style.font.

TooltipStyle

Authored overlay for TooltipStyle. Tooltip box style — all cascade keys for the hover bubble.

Field	Type	Optional	Description
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default tooltip value format string; theme always provides this.
background	str	✓	Tooltip background color (CSS color string); theme always provides this.
line_height	float	✓	Tooltip line-height multiplier; theme always provides this.
max_width	float	✓	Maximum tooltip width in pixels; theme always provides this.
gap	float	✓	Gap in pixels between label and value columns; theme always provides this.
font	FontStyle	✓	Tooltip font overrides (size etc.); cascade fills missing fields. Unset fields fall back to style.charts.font.
padding	PaddingStyle	✓	Tooltip inner padding (4 sides in pixels); theme always provides this.
label	TooltipSlotStyle	✓	Label-column font overrides (color, weight).
value	TooltipSlotStyle	✓	Value-column font overrides (color, weight).
border	TooltipBorderStyle	✓	Tooltip border style; theme always provides this.
shadow	TooltipShadowStyle	✓	Tooltip drop-shadow config; theme always provides this.
swatch	TooltipSwatchStyle	✓	Series colour swatch size/shape; theme always provides this.
active_marker	enum: "fill", "triangle"	✓	How the hovered row is marked in a multi-row (x-unified) tooltip: 'fill' tints the row background (default); 'triangle' draws an edge-flush wedge in the box's left padding instead. Theme always provides this.

ViewStyle

Authored overlay for ViewStyle.

Field	Type	Optional	Description
stroke	str	✓	Plot area border stroke color; None means no border.
continuous_width	float	✓	Default plot width for continuous (quantitative) scales in pixels.
continuous_height	float	✓	Default plot height for continuous (quantitative) scales in pixels.
discrete_width	float	✓	Default plot width for discrete (ordinal/nominal) scales in pixels; None means auto.
discrete_height	float	✓	Default plot height for discrete (ordinal/nominal) scales in pixels; None means auto.

GlobalMarksStyle

Authored overlay for GlobalMarksStyle. Global mark defaults: one MarkStyle per VL mark type.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Global bar mark defaults.
line	LineMarkStyle	✓	Global line mark defaults.
area	AreaMarkStyle	✓	Global area mark defaults.
point	PointMarkStyle	✓	Global point mark defaults.
slice	SliceMarkStyle	✓	Global slice (arc/pie) mark defaults.
text	TextMarkStyle	✓	Global text mark defaults.
rule	RuleMarkStyle	✓	Global rule mark defaults.
rect	RectMarkStyle	✓	Global rect mark defaults.
circle	CircleMarkStyle	✓	Global circle mark defaults.
geoshape	GeoshapeMarkStyle	✓	Global geoshape mark defaults.

HistogramChartStyle

Authored overlay for HistogramChartStyle. Histogram chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
preferred_width	float	✓	Preferred chart width in pixels. Falls back to style.charts.preferred_width.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
background	str	✓	Chart-local background color override; None inherits from theme.
color	ColorStyle	✓	Chart color: static mark paint, categorical palette, and/or gradient scale.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
legend	LegendStyle	✓	Chart legend style.
axis	BaseAxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisXStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisYStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	QuantitativeAxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	BandAxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
bin_maxbins	int	✓	Maximum number of bins for auto-binning.
marks	HistogramChartMarksStyle	✓	Histogram-family mark overrides. Unset fields fall back to style.charts.marks.

SeriesLabelStyle

Authored overlay for SeriesLabelStyle. Series-label primitive — typography for any text mark that names a

Field	Type	Optional	Description
font	SeriesLabelFontStyle	✓	Series label font style overrides; cascade fills missing fields from charts.font. Unset fields fall back to style.charts.font.

LayoutGapStyle

Authored overlay for LayoutGapStyle.

Field	Type	Optional	Description
gap	float	✓	Gap between layout items in pixels.

GridLayoutStyle

Authored overlay for GridLayoutStyle.

Field	Type	Optional	Description
columns	int	✓	Number of columns in the grid layout.
gap	float	✓	Gap between grid cells in pixels.

TabsStyle

Authored overlay for TabsStyle.

Field	Type	Optional	Description
bar_height	float	✓	Tab bar height in pixels.
border	BorderStyle	✓	Tab bar border style.
font	FontStyle	✓	Tab label font style overrides. Unset fields fall back to style.font.
active_weight	str	✓	Font weight for the active tab label.
inactive_weight	str	✓	Font weight for inactive tab labels.
title_baseline_offset	float	✓	Vertical offset to align SVG tab label baseline in pixels.

DetailsStyle

Authored overlay for DetailsStyle.

Field	Type	Optional	Description
summary_height	float	✓	Height of the details summary (collapsed) row in pixels.
border	BorderStyle	✓	Details element border style.
font	FontStyle	✓	Details summary font style overrides. Unset fields fall back to style.font.
arrow	DetailsArrowStyle	✓	Expand/collapse arrow glyph layout and font style.
label_x	float	✓	X position of the details summary label text in pixels.
text_baseline_offset	float	✓	Vertical offset to align SVG details text baseline in pixels.
content_y_offset	float	✓	Y offset of the expanded details content area in pixels.

VariablesLabelStyle

Authored overlay for VariablesLabelStyle. Per-label font substyle for variable controls. Cascades from variables.font.

Field	Type	Optional	Description
font	FontStyle	✓	Variable label font style overrides. Unset fields fall back to style.variables.font.

VariablesValueStyle

Authored overlay for VariablesValueStyle. Per-value font substyle for variable controls. Cascades from variables.font.

Field	Type	Optional	Description
font	FontStyle	✓	Variable value font style overrides. Unset fields fall back to style.variables.font.

VariablesPlaceholderStyle

Authored overlay for VariablesPlaceholderStyle. Per-placeholder font substyle for variable controls.

Field	Type	Optional	Description
font	FontStyle	✓	Variable placeholder-text font style overrides. Unset fields fall back to style.variables.font.

InputStyle

Authored overlay for InputStyle.

Field	Type	Optional	Description
height	float	✓	Input control height in pixels.
border	BorderStyle	✓	Input border style.
focus_color	str	✓	Input focus ring color. Falls back to style.accent.
background	str	✓	Input background color.
padding	SpacingValues	✓	Input inner padding in pixels.
widths	InputWidths	✓	Per-input-type default widths.
range	RangeDefaults	✓	Range input default min/max/step values.

FooterRule

Authored overlay for FooterRule. Hairline rule above the footer attribution text. None = no rule.

Field	Type	Optional	Description
color	str	✓	Rule stroke color.
stroke_width	float	✓	Rule stroke width in pixels.

ScaleTargetConfig

Authored overlay for ScaleTargetConfig. Scale configuration for a single style target (background or color).

Field	Type	Optional	Description
palette	str | list[str] | list[float] | enum: "accent", "bluegreen", "blueorange", "bluepurple", "blues", "brownbluegreen", "browns", "category-6-tonal-blue", "category-6-tonal-brown", "category-6-tonal-green", "category-6-tonal-orange", "category-6-tonal-purple", "category10", "category20", "category20b", "category20c", "cividis", "dark2", "darkblue", "darkgold", … (96 more; see the JSON Schema)	✓	Color palette: a named Dataface palette or Vega scheme, a CSS color list for categorical, or a float list for relative stops.
domain	enum: "data"	✓	Scale domain source ('data' uses the data extent, widened to nice round bounds when nice is true; None uses explicit min/max).
min	float | int	✓	Minimum scale domain value (overrides data minimum).
max	float | int	✓	Maximum scale domain value (overrides data maximum).
nice	bool	✓	Widen a data-derived domain to round ('nice') bounds and label every nice tick on the legend, mirroring Vega-Lite's own scale.nice. Applies to the color scale a gradient legend labels, not the x/y position scale. Ignored once min or max is set — a single-sided bound already fixes that edge exactly. Widening is currently honored on heatmap's themed color gradient only; geoshape's choropleth honors nice: false (exact endpoint labels) but not nice: true's widening.
null_color	str	✓	Color assigned to null values.
hinge	float | enum: "auto"	✓	Diverging scale midpoint value, or 'auto' to use the data midpoint.
arm_mode	enum: "asymmetric", "symmetric"	✓	How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms).

CategoricalColorStyle

Authored overlay for CategoricalColorStyle. Categorical palette config: per-series colors and single-series ink list.

Field	Type	Optional	Description
palette	str | list[str] | enum: "category-6-tonal-blue", "category-6-tonal-brown", "category-6-tonal-green", "category-6-tonal-orange", "category-6-tonal-purple", "dbt-creams", "dbt-div-blue-red", "dbt-div-blue-red-dark", "dbt-div-coolwarm", "dbt-div-coolwarm-dark", "dbt-div-crimson-green", "dbt-div-crimson-green-dark", "dbt-div-orange-teal", "dbt-div-orange-teal-dark", "dbt-div-sunset", "dbt-div-sunset-dark", "dbt-grays", "dbt-seq-amber", "dbt-seq-amber-dark", "dbt-seq-blue", … (29 more; see the JSON Schema)	✓	Categorical color palette: list of stops or a named palette. Expanded to list[str] at validation time.
single_series_palette	str | list[str] | enum: "category-6-tonal-blue", "category-6-tonal-brown", "category-6-tonal-green", "category-6-tonal-orange", "category-6-tonal-purple", "dbt-creams", "dbt-div-blue-red", "dbt-div-blue-red-dark", "dbt-div-coolwarm", "dbt-div-coolwarm-dark", "dbt-div-crimson-green", "dbt-div-crimson-green-dark", "dbt-div-orange-teal", "dbt-div-orange-teal-dark", "dbt-div-sunset", "dbt-div-sunset-dark", "dbt-grays", "dbt-seq-amber", "dbt-seq-amber-dark", "dbt-seq-blue", … (29 more; see the JSON Schema)	✓	Ordered list of single-series mark inks (must be non-empty when set), or a palette name.

LegendLabelStyle

Authored overlay for LegendLabelStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Legend element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between legend symbol and element text in pixels.
max_width	float	✓	Maximum label width in pixels; maps to VL labelLimit. None uses Vega-Lite's default.

LegendTitleStyle

Authored overlay for LegendTitleStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Legend element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between legend symbol and element text in pixels.
visible	bool	✓	Show the legend title; None = shown, False = suppressed (VL legend.title: null).

BaseAxisGridStyle

Authored overlay for BaseAxisGridStyle. Grid line style for all axis variants.

Field	Type	Optional	Description
visible	bool	✓	Show grid lines; None inherits from parent axis.
opacity	float	✓	Grid line opacity; None uses Vega-Lite's default.
width	float	✓	Grid line width in pixels; None uses Vega-Lite's default.
color	str	✓	Grid line color; None uses Vega-Lite's default.
dash	list[float]	✓	Dash pattern for grid lines; None renders a solid line.

AxisLineStyle

Authored overlay for AxisLineStyle. Axis domain/baseline line style. Renamed from AxisDomainStyle —

Field	Type	Optional	Description
visible	bool	✓	Show the axis domain line; None inherits from parent axis.
width	float	✓	Domain line width in pixels; None uses Vega-Lite's default.
color	str	✓	Domain line color; None uses Vega-Lite's default.

AxisTicksStyle

Authored overlay for AxisTicksStyle. Tick marks on an axis: visibility, color, size, and cadence.

Field	Type	Optional	Description
visible	bool	✓	Show axis ticks; None inherits from parent axis.
color	str	✓	Tick color; None uses Vega-Lite's default.
length	float	✓	Tick length in pixels; None uses Vega-Lite's default.
width	float	✓	Tick stroke width in pixels; None uses Vega-Lite's default.
offset	float	✓	Pixel offset of ticks from their default position; None means no offset.
count	int	✓	Target number of axis ticks — a target everywhere, never an exact count. On the measure axis (axis_y) the renderer computes an explicit round-numbered ladder of at most this many ticks. On axis_x it passes through as VL's axis.tickCount: a temporal scale honours it closely, a quantitative one rounds to a nearby round-numbered ladder. To name the interval instead of the count, author ticks.step on a quantitative axis_x. An ordinal axis_x has no tick-count concept and ignores this.
step	int	✓	Tick interval on axis_x. Alongside ticks.time_unit it is a multiple of that calendar grain (time_unit: year, step: 5 -> a tick every 5 years). On its own it is a numeric interval for a quantitative axis (step: 1000 -> a tick every 1000), and acts as a floor rather than a fixed ladder, so the axis keeps covering the data as its range grows. A bare step on an axis that is not quantitative is an error, not a no-op; axis_y rejects step entirely (set ticks.count there instead).

AxisLabelStyle

Authored overlay for AxisLabelStyle. Axis label: font + padding + VL-passthrough.

Field	Type	Optional	Description
font	FontStyle	✓	Axis element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between axis labels and ticks in pixels; None inherits from parent axis.
max_width	float	✓	Maximum label width in pixels; None uses Vega-Lite's default (180px).
angle	float	✓	Label rotation angle in degrees; None uses Vega-Lite's default.
align	enum: "left", "right", "center", "inward", "outward"	✓	Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default.
overlap	AxisLabelOverlapConfig	✓	Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; they are applied in fixed order skip→tilt. On bucketed temporal axes, skip thins label visibility to a coarser calendar period without changing the axis or label time unit.
min_gap	float	✓	Minimum pixel gap between labels; None uses Vega-Lite's default (0px).
visible	bool	✓	Show axis labels; None uses Vega-Lite's default (labels shown).
expr	str	✓	Custom Vega expression for label text; None uses smart temporal defaults when applicable.
bound	bool | float	✓	Hide labels that overflow the axis range; None uses Vega-Lite's default.
flush	bool | float	✓	Align first/last label flush with the scale range; None uses Vega-Lite's default.
offset	float	✓	Pixel offset of the label from its tick anchor; None uses Vega-Lite's default.
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Tick value format string; None uses auto-format.

AxisTitleStyle

Authored overlay for AxisTitleStyle. Axis title typography — deliberately thin. A title is one short static

Field	Type	Optional	Description
font	FontStyle	✓	Axis title font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between axis title and labels in pixels; None uses Vega-Lite's default.
angle	float	✓	Title rotation angle in degrees; None uses Vega-Lite's default.
align	enum: "left", "right", "center", "inward", "outward"	✓	Horizontal text alignment of the title. 'left'/'right'/'center' are absolute. 'inward'/'outward' resolve against the axis's own left/right edge, same as label.align; a no-op on an axis with no left/right edge. None uses Vega-Lite's default.
visible	bool	✓	Show the axis title; None uses Vega-Lite's default (title shown). An explicit value you set — on the board or on a single chart — wins over the title an authored x_label/y_label would force on.

BaseScaleStyle

Authored overlay for BaseScaleStyle. Universal + continuous-only scale config.

Field	Type	Optional	Description
round	bool	✓	Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).
clamp	bool	✓	Clamp values to scale domain; None uses Vega-Lite's default (no clamping).
nice	bool	✓	Round the axis domain to nice values; None uses Vega-Lite's default. Forwards natively to Vega-Lite's scale.nice.
padding	float	✓	Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type.
headroom	float	✓	Fractional breathing room at measure-axis edges, exact (never nice-rounded). Zero-anchored axes (bar; line/area/scatter near zero): domain_max = data_max * (1 + headroom). Zoomed axes (line/area/scatter far from zero): both edges expand — domain_max = data_max + headroom * span; domain_min = data_min - headroom * span. None inherits the theme default; 0 disables headroom. Ignored with an explicit domain or stack: normalize.
values	list[Any]	✓	Explicit tick values; None uses Vega-Lite's auto tick values.
continuous	ScaleContinuousStyle	✓	Continuous-scale overrides (type, domain, zero, log/pow/symlog params); None means no override.

DimensionTicksStyle

Authored overlay for DimensionTicksStyle. axis_x-only: adds the calendar unit that anchors a step cadence.

Field	Type	Optional	Description
visible	bool	✓	Show axis ticks; None inherits from parent axis.
color	str	✓	Tick color; None uses Vega-Lite's default.
length	float	✓	Tick length in pixels; None uses Vega-Lite's default.
width	float	✓	Tick stroke width in pixels; None uses Vega-Lite's default.
offset	float	✓	Pixel offset of ticks from their default position; None means no offset.
count	int	✓	Target number of axis ticks — a target everywhere, never an exact count. On the measure axis (axis_y) the renderer computes an explicit round-numbered ladder of at most this many ticks. On axis_x it passes through as VL's axis.tickCount: a temporal scale honours it closely, a quantitative one rounds to a nearby round-numbered ladder. To name the interval instead of the count, author ticks.step on a quantitative axis_x. An ordinal axis_x has no tick-count concept and ignores this.
step	int	✓	Tick interval on axis_x. Alongside ticks.time_unit it is a multiple of that calendar grain (time_unit: year, step: 5 -> a tick every 5 years). On its own it is a numeric interval for a quantitative axis (step: 1000 -> a tick every 1000), and acts as a floor rather than a fixed ladder, so the axis keeps covering the data as its range grows. A bare step on an axis that is not quantitative is an error, not a no-op; axis_y rejects step entirely (set ticks.count there instead).
time_unit	enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none"	✓	Step-anchored tick cadence unit; None disables step-anchored ticks.

DimensionLabelStyle

Authored overlay for DimensionLabelStyle. AxisLabelStyle + dimension-axis-only label fields.

Field	Type	Optional	Description
font	FontStyle	✓	Axis element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between axis labels and ticks in pixels; None inherits from parent axis.
max_width	float	✓	Maximum label width in pixels; None uses Vega-Lite's default (180px).
angle	float	✓	Label rotation angle in degrees; None uses Vega-Lite's default.
align	enum: "left", "right", "center", "inward", "outward"	✓	Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default.
overlap	AxisLabelOverlapConfig	✓	Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; they are applied in fixed order skip→tilt. On bucketed temporal axes, skip thins label visibility to a coarser calendar period without changing the axis or label time unit.
min_gap	float	✓	Minimum pixel gap between labels; None uses Vega-Lite's default (0px).
visible	bool	✓	Show axis labels; None uses Vega-Lite's default (labels shown).
expr	str	✓	Custom Vega expression for label text; None uses smart temporal defaults when applicable.
bound	bool | float	✓	Hide labels that overflow the axis range; None uses Vega-Lite's default.
flush	bool | float	✓	Align first/last label flush with the scale range; None uses Vega-Lite's default.
offset	float	✓	Pixel offset of the label from its tick anchor; None uses Vega-Lite's default.
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Tick value format string; None uses auto-format.
time_unit	enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none"	✓	Label cadence for temporal axes; None inherits from the parent axis time_unit.
tilt_increments	list[float]	✓	Descending tilt angles for label overlap resolution on discrete x-axes; None disables tilt.
values	list[Any]	✓	Dates to keep label text on, chosen from among the axis's ticks (whatever axis_x.scale.values or the auto-fill cadence already produced) — this filters which ticks show text, it does not add or remove ticks. Every tick not in this list keeps its position and gridline but has its label blanked. Set axis_x.scale.values separately to change tick/grid density itself. Temporal x-axes only; not supported on a horizontal bar's categorical axis. None labels every tick as usual.

XScaleStyle

Authored overlay for XScaleStyle. Scale config for axis_x.scale only.

Field	Type	Optional	Description
round	bool	✓	Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).
clamp	bool	✓	Clamp values to scale domain; None uses Vega-Lite's default (no clamping).
nice	bool	✓	Round the axis domain to nice values; None uses Vega-Lite's default. Forwards natively to Vega-Lite's scale.nice.
padding	float	✓	Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type.
headroom	float	✓	Fractional breathing room at measure-axis edges, exact (never nice-rounded). Zero-anchored axes (bar; line/area/scatter near zero): domain_max = data_max * (1 + headroom). Zoomed axes (line/area/scatter far from zero): both edges expand — domain_max = data_max + headroom * span; domain_min = data_min - headroom * span. None inherits the theme default; 0 disables headroom. Ignored with an explicit domain or stack: normalize.
values	list[Any]	✓	Explicit tick values; None uses Vega-Lite's auto tick values.
continuous	ScaleContinuousStyle	✓	Continuous-scale overrides (type, domain, zero, log/pow/symlog params); None means no override.
x_reverse	bool	✓	Reverse the x-axis scale direction; None means no reversal.

MeasureGridStyle

Authored overlay for MeasureGridStyle. BaseAxisGridStyle + zero-baseline override for the measure (y) axis.

Field	Type	Optional	Description
visible	bool	✓	Show grid lines; None inherits from parent axis.
opacity	float	✓	Grid line opacity; None uses Vega-Lite's default.
width	float	✓	Grid line width in pixels; None uses Vega-Lite's default.
color	str	✓	Grid line color; None uses Vega-Lite's default.
dash	list[float]	✓	Dash pattern for grid lines; None renders a solid line.
zero	AxisGridZeroStyle	✓	Zero-baseline gridline style; None inherits from parent axis.

AxisMirrorStyle

Per-edge label override for the mirrored axis_y.mirror ghost axis.

Field	Type	Optional	Description
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Tick value format string for the mirrored edge; None reuses the primary axis's format.
expr	str	✓	Custom Vega expression for the mirrored edge's label text; None reuses the primary axis's label expression.

RuleStyle

Authored overlay for RuleStyle. Shared rule-line primitive: width, color, continuous mode.

Field	Type	Optional	Description
width	float	✓	Rule line width in pixels.
color	str	✓	Rule color; None inherits from theme.
continuous	bool	✓	Draw a continuous full-width rule (true) or only under columns (false).

DataTableRowStyle

Authored overlay for DataTableRowStyle.

Field	Type	Optional	Description
padding	DataTableRowPaddingStyle	✓	Row padding style.
rule	RuleStyle	✓	Row bottom rule style.

DataTableLabelStyle

Authored overlay for DataTableLabelStyle. Row label styling.

Field	Type	Optional	Description
font	FontStyle	✓	Row label font style overrides. Unset fields fall back to style.charts.data_table.font.

BarMarkStyle

Authored overlay for BarMarkStyle. Bar mark geometry and stroke. Chart-level bar fields live on BarChartStyle.

Field	Type	Optional	Description
border	BorderStyle	✓	Bar border style (color/width also serve as the bar stroke).
padding	float	✓	Padding around bar marks in pixels.
size	float	✓	Bar width in pixels (fixed-width mode).
band_width	float	✓	Bar width as a fraction of the band step (0–1).
labels	BarLabelsStyle	✓	Value label style for bar marks.
total_label	BarTotalLabelStyle	✓	Stack total label style. Only takes effect on stacked bar charts; ignored otherwise.

TextMarkStyle

Authored overlay for TextMarkStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Text mark font style overrides. Unset fields fall back to style.charts.font.
align	str	✓	Horizontal text alignment for text marks.

LayerAxisYScale

Per-layer y-axis scale patch.

Field	Type	Optional	Description
domain	list[float]	✓	Explicit [min, max] domain for this layer's y scale.

LayerAxisYTicks

Per-layer y-axis tick patch.

Field	Type	Optional	Description
count	int	✓	Requested number of y-axis ticks for this layer.

LayerAxisYGrid

Per-layer y-axis grid patch.

Field	Type	Optional	Description
visible	bool	✓	Whether to show grid lines on this layer's y axis.

LayerAxisYLabel

Per-layer y-axis label format patch.

Field	Type	Optional	Description
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	d3 format string for this layer's y-axis tick labels.

LineMarkStyle

Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. Point mark lives on PointMarkStyle.

Field	Type	Optional	Description
stroke	StrokeStyle	✓	Line stroke style.
curve	enum: "linear", "monotone", "natural", "basis", "cardinal", "step", "step-before", "step-after"	✓	Line interpolation curve, one of a fixed set: 'linear', 'monotone', 'natural', 'basis', 'cardinal', 'step', 'step-before', 'step-after'. On a categorical (nominal/ordinal) x-axis, 'step' draws a full-band-width plateau per x-value instead of VL's centered step; on a continuous (temporal/quantitative) x-axis it passes straight through to VL's native step.
connect	bool	✓	For curve='step' on a categorical (band) x-axis, whether adjacent band plateaus are joined by vertical jumps (True/None) or left as disconnected segments (False). No-op for other curves or a continuous x-axis.
disconnected_cap	enum: "butt", "round", "square"	✓	Stroke line cap for the sub-paths of a disconnected band-step (curve='step' + connect=False on a categorical x-axis). Each band is its own flat path there, so the cap lands on every band edge rather than only the two ends of one continuous line; 'butt' keeps plateaus flush with the band. Overrides stroke.cap in that geometry only — every other line keeps stroke.cap.
halo_multiplier	float	✓	Halo stroke width multiplier relative to stroke.width; 0 disables the halo.
labels	PointLabelsStyle	✓	Value label style for line marks.

PointMarkStyle

Authored overlay for PointMarkStyle. Point mark style (data-point markers on scatter/point/line/area charts).

Field	Type	Optional	Description
size	float	✓	Point size in square pixels; 0 disables points on line charts.
color	str	✓	Point color; None inherits the series color.
shape	str	✓	Point shape (e.g. 'circle', 'square'); None uses VL default.
opacity	float	✓	Point opacity 0–1; None uses VL default.
filled	bool	✓	Whether points are filled; None uses VL default.
fill	str	✓	Point interior fill color; only applied when filled=false.
stroke_width	float	✓	Stroke width in pixels for hollow point rings; None uses VL default.
labels	PointLabelsStyle	✓	Value label style for point marks. On line charts, setting marks.point.labels is an alias for marks.line.labels.

RuleMarkStyle

Authored overlay for RuleMarkStyle. Rule (reference line) mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	FontColorStrokeStyle	✓	Mark stroke style.

AreaMarkStyle

Authored overlay for AreaMarkStyle. Area mark fill opacity and shape.

Field	Type	Optional	Description
opacity	float	✓	Area fill opacity (0–1).
curve	enum: "linear", "monotone", "natural", "basis", "cardinal", "step", "step-before", "step-after"	✓	Area interpolation curve, one of a fixed set: 'linear', 'monotone', 'natural', 'basis', 'cardinal', 'step', 'step-before', 'step-after'. On a categorical (nominal/ordinal) x-axis, 'step' draws a full-band-width plateau per x-value instead of VL's centered step; on a continuous (temporal/quantitative) x-axis it passes straight through to VL's native step. Applied to both the fill and its edge line (marks.line) so they trace the same path.
backdrop	bool	✓	Whether to paint an opaque fill backdrop behind the area.
stacked	AreaStackedMarkStyle	✓	Recipe override applied when the chart's stack mode is non-false: solid fill + full-perimeter background-color stroke.

AreaLineStyle

Authored overlay for AreaLineStyle. Stroke/halo/labels for an area chart's top-edge line and value labels.

Field	Type	Optional	Description
stroke	StrokeStyle	✓	Area top-edge line stroke style.
halo_multiplier	float	✓	Halo stroke width multiplier relative to stroke.width; 0 disables the halo.
labels	PointLabelsStyle	✓	Value label style for the area's plotted points; inherits from global.

RectMarkStyle

Authored overlay for RectMarkStyle. Rect mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

TotalSlotStyle

Authored overlay for TotalSlotStyle. Theme slot for one text element of the donut center total.

Field	Type	Optional	Description
font	FontStyle	✓	Donut center total element font style overrides. Unset fields fall back to style.charts.font.

SliceMarkStyle

Authored overlay for SliceMarkStyle. Pie/donut slice mark — mark-level paint and layout only.

Field	Type	Optional	Description
opacity	float	✓	Arc slice opacity (0–1); None means not overridden at this level.
gap	float	✓	Angular gap between slices in radians.
corner_radius	float	✓	Corner radius of arc slices in pixels.
stroke	StrokeStyle	✓	Arc slice stroke style.
labels	SliceLabelsStyle	✓	Per-slice label style.

TableRowStripeStyle

Authored overlay for TableRowStripeStyle. Alternating row stripe style.

Field	Type	Optional	Description
color	str	✓	Alternating stripe background color; None means no alternating row fill.

TableRowRolesStyle

Authored overlay for TableRowRolesStyle.

Field	Type	Optional	Description
summary	TableRowRoleStyle	✓	Style for summary role rows.
total	TableRowRoleStyle	✓	Style for total role rows.

SparkConfig

Configuration for spark charts (inline sparklines) in table columns.

Field	Type	Optional	Description
type	enum: "line", "area", "bar", "bar-normalize", "column", "columns"	✓	Spark chart type (line, area, bar, bar-normalize, column, columns).
color	str	✓	Color for the spark mark.
height	int	✓	Spark chart height in pixels.
width	int	✓	Spark chart width in pixels.
last_visible	bool	✓	Highlight the last data point (line/area spark charts).
min_max_visible	bool	✓	Annotate the min and max data points (line/area spark charts).
fill_opacity	float	✓	Fill opacity for area spark charts (0–1).
max	float	✓	Maximum value for bar-normalize range scaling.
thresholds	dict[int | float, str]	✓	Color thresholds for bar / bar-normalize: {value: CSS color string}.
background	str	✓	Background track color for bar-normalize chart.
border_radius	float	✓	Border radius for bar-normalize track in pixels.
value_visible	bool	✓	Show numeric value label alongside the bar.
value_suffix	str	✓	Suffix appended to the displayed value label (e.g., '%').

ColumnScaleConfig

Scale-based continuous color mapping for a table column.

Field	Type	Optional	Description
background	ScaleTargetConfig	✓	Continuous background color mapping for this column.
color	ScaleTargetConfig	✓	Continuous text color mapping for this column.

SparkEmptyStyle

Authored overlay for SparkEmptyStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the empty sparkline placeholder in pixels.
stroke	StrokeStyle	✓	Empty-state placeholder stroke style.

SparkSingleValueStyle

Authored overlay for SparkSingleValueStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the single-value sparkline in pixels.
marker_radius	float	✓	Radius of the single-value marker circle in pixels.

SparkColumnsStyle

Authored overlay for SparkColumnsStyle. Inline spark.type: columns (multi-value vertical bars) defaults.

Field	Type	Optional	Description
gap	float	✓	Gap between column bars in pixels.
padding	float	✓	Horizontal outer padding of the columns sparkline in pixels.
min_bar_height	float	✓	Minimum rendered bar height in pixels.
border	BorderStyle	✓	Column bar border style.

SparkColumnStyle

Authored overlay for SparkColumnStyle. Inline spark.type: column (single vertical bar) defaults.

Field	Type	Optional	Description
width	float	✓	Spark column default width in pixels.
height	float	✓	Spark column default height in pixels.

SparkBarCellStyle

Authored overlay for SparkBarCellStyle. Inline spark.type: bar and bar-normalize (single horizontal bar) defaults.

Field	Type	Optional	Description
background	str	✓	Track background color - fill-grade, pinned per theme.
color	str	✓	Bar fill color; None seeds from style.charts.color.categorical.single_series_palette[0].
default_max	float	✓	Default maximum value for bar scale when no explicit max is authored.
border	BorderStyle	✓	Spark bar border style.
font	FontStyle	✓	Spark bar cell font style overrides. Unset fields fall back to style.charts.font.
label	SparkBarLabelStyle	✓	Spark bar inline label style.

SparkAreaStyle

Authored overlay for SparkAreaStyle.

Field	Type	Optional	Description
fill_opacity	float	✓	Spark area fill opacity (0–1).

GeoshapeMarkStyle

Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boundary stroke.

Field	Type	Optional	Description
fill	str	✓	Neutral geoshape fill color.
stroke	StrokeStyle	✓	Geoshape boundary stroke style.

ColumnRuleStyle

Authored overlay for ColumnRuleStyle. Vertical rule drawn between prose columns, structured like BorderStyle.

Field	Type	Optional	Description
width	float	✓	Rule line width in pixels.
color	str	✓	Rule color as a CSS color string.
style	enum: "solid", "dashed", "dotted"	✓	Rule line style.

TooltipSlotStyle

Authored overlay for TooltipSlotStyle. Typography for a single tooltip slot (label or value).

Field	Type	Optional	Description
font	FontStyle	✓	Font overrides for this tooltip slot (color, weight). Unset fields fall back to style.charts.font.

TooltipBorderStyle

Authored overlay for TooltipBorderStyle. Tooltip box border — all fields required; theme YAML supplies defaults.

Field	Type	Optional	Description
color	str	✓	Border color as a CSS color string.
width	float	✓	Border width in pixels.
radius	float	✓	Border corner radius in pixels.

TooltipShadowStyle

Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies the shadow expression when visible=true.

Field	Type	Optional	Description
visible	bool	✓	Show a drop-shadow on the tooltip box; theme always provides this.

TooltipSwatchStyle

Authored overlay for TooltipSwatchStyle. Series colour swatch in the tooltip — the mark-coloured chip next to each

Field	Type	Optional	Description
size	float	✓	Swatch edge length in pixels (square).
radius	float	✓	Swatch corner radius in pixels (0 = square, ~half of size = circle).

CircleMarkStyle

Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

HistogramChartMarksStyle

Authored overlay for HistogramChartMarksStyle. Histogram-family mark overrides.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Bar mark overrides; inherits from global.
rule	RuleMarkStyle	✓	Rule mark overrides; None inherits global.

SeriesLabelFontStyle

Authored overlay for SeriesLabelFontStyle. Series-label typography with a compact width-tier size.

Field	Type	Optional	Description
family	str	✓	Font family name (e.g., 'sans-serif', 'Roboto').
color	str	✓	Text color as a CSS color string.
size	float	✓	Font size in pixels.
weight	str | float	✓	Font weight (e.g., 'bold', 400, 700).
style	enum: "normal", "italic"	✓	Font style (normal or italic).
decoration	enum: "none", "line-through", "underline"	✓	Text decoration (underline, line-through, or none).
case	enum: "none", "sentence", "title", "upper", "lower", "slug", "camel"	✓	Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change.
line_height	float	✓	Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML.
compact_size	float	✓	Series-label font size in pixels on tiny and narrow cards.
compact_weight	str | float	✓	Series-label font weight on tiny and narrow cards.

DetailsArrowStyle

Authored overlay for DetailsArrowStyle. Layout and font style for the expand/collapse arrow chevron.

Field	Type	Optional	Description
x	float	✓	X position of the arrow in pixels.
font	DetailsArrowFontStyle	✓	Arrow glyph font style.

InputWidths

Authored overlay for InputWidths.

Field	Type	Optional	Description
text	float	✓	Default width for text inputs in pixels.
number	float	✓	Default width for number inputs in pixels.
range	float	✓	Default width for range inputs in pixels.
slider_value_min	float	✓	Minimum width for slider value display in pixels.
checkbox	float	✓	Default width for checkbox inputs in pixels.
daterange	float	✓	Default width for daterange chip triggers in pixels.

RangeDefaults

Authored overlay for RangeDefaults.

Field	Type	Optional	Description
default_min	float	✓	Default minimum value for range inputs.
default_max	float	✓	Default maximum value for range inputs.
default_step	float	✓	Default step size for range inputs.

AxisLabelOverlapConfig

Authored overlay for AxisLabelOverlapConfig. Two-bool overlap strategy enablement for x-axis labels.

Field	Type	Optional	Description
tilt	bool	✓	Enable label tilt strategy; None inherits from parent axis.
skip	bool	✓	Enable temporal label thinning; ignored on categorical axes; None inherits from parent axis.

ScaleContinuousStyle

Authored overlay for ScaleContinuousStyle. Continuous-scale-only config: type, domain, zero-baseline, log/pow/symlog params.

Field	Type	Optional	Description
zero	bool | enum: "auto"	✓	Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite.
type	enum: "linear", "log", "pow", "sqrt", "symlog", "temporal"	✓	Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a Dataface escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored domain of ISO dates can extend the visible range past the data extent. None lets Dataface/Vega-Lite infer from the field type.
domain	list[Any]	✓	Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements — Dataface only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. When type: temporal is set, both elements must be ISO-8601 date/datetime strings.
log	ScaleLogStyle	✓	Log-scale param (base); only meaningful with type: log.
pow	ScalePowStyle	✓	Power-scale param (exponent); only meaningful with type: pow.
symlog	ScaleSymlogStyle	✓	Symlog-scale param (constant); only meaningful with type: symlog.

AxisGridZeroStyle

Authored overlay for AxisGridZeroStyle. Zero-baseline gridline color and width overrides.

Field	Type	Optional	Description
color	str	✓	Color of the zero-baseline grid line; None inherits from parent axis.
width	float	✓	Width of the zero-baseline grid line in pixels; None inherits from parent axis.

DataTableRowPaddingStyle

Authored overlay for DataTableRowPaddingStyle.

Field	Type	Optional	Description
vertical	float	✓	Vertical (top/bottom) padding inside data_table rows in pixels.
horizontal	float	✓	Horizontal (left/right) padding inside data_table rows in pixels.

BarLabelsStyle

Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLabelsStyle with bar-specific positions.

Field	Type	Optional	Description
visible	bool	✓	Show numeric value labels on each mark; False by default.
field	str	✓	Column to source label text from; None uses the chart's y-field.
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format string for value labels.
dx	int	✓	Horizontal pixel offset for value labels; overrides the position default.
dy	int	✓	Vertical pixel offset for value labels; overrides the position default.
font	FontStyle	✓	Value label font style (color, size, family, etc.).
position	enum: "above", "top", "middle", "middle_aligned", "bottom"	✓	Label position relative to the bar. 'above' places labels above the bar top (outside). 'top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. 'middle_aligned' centers all labels at a common height (mean of bar heights / 2). 'bottom' places labels just inside the bottom edge.

BarTotalLabelStyle

Authored overlay for BarTotalLabelStyle. Stack total label style for bar marks.

Field	Type	Optional	Description
visible	bool	✓	Show stack total labels above each bar stack. Only takes effect on stacked bar charts; ignored otherwise.
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format string for stack total labels.
dx	int	✓	Horizontal pixel offset for stack total labels.
dy	int	✓	Vertical pixel offset for stack total labels.
font	FontStyle	✓	Stack total label font style overrides; cascade fills missing fields from charts.font. Unset fields fall back to style.charts.font.

StrokeStyle

Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark families.

Field	Type	Optional	Description
color	str	✓	Stroke color as a CSS color string.
width	float	✓	Stroke width in pixels.
cap	enum: "butt", "round", "square"	✓	Stroke line cap style (butt, round, or square).
join	enum: "miter", "round", "bevel"	✓	Stroke line join style (miter, round, or bevel).
dasharray	str	✓	SVG stroke-dasharray pattern (e.g. '4 2').

PointLabelsStyle

Authored overlay for PointLabelsStyle. Point/line mark value-label config. Used by both LineMarkStyle and PointMarkStyle.

Field	Type	Optional	Description
visible	bool	✓	Show numeric value labels on each mark; False by default.
field	str	✓	Column to source label text from; None uses the chart's y-field.
format	str | enum: "compact", "currency", "currency_compact", "currency_whole", "date_short", "delta", "integer", "number", "number_default", "percent", "percent_delta", "percent_whole", "year"	✓	Number format string for value labels.
dx	int	✓	Horizontal pixel offset for value labels; overrides the position default.
dy	int	✓	Vertical pixel offset for value labels; overrides the position default.
font	FontStyle	✓	Value label font style (color, size, family, etc.).
position	enum: "top", "bottom", "left", "right", "middle"	✓	Label position relative to the point. 'top' places labels above the point. 'bottom' places labels below. 'left' to the left. 'right' to the right. 'middle' centers on the point.

FontColorStrokeStyle

Authored overlay for FontColorStrokeStyle. Stroke for rule marks whose color defaults to the root font color.

Field	Type	Optional	Description
color	str	✓	Stroke color. Falls back to style.font.color.
width	float	✓	Stroke width in pixels.
cap	enum: "butt", "round", "square"	✓	Stroke line cap style (butt, round, or square).
join	enum: "miter", "round", "bevel"	✓	Stroke line join style (miter, round, or bevel).
dasharray	str	✓	SVG stroke-dasharray pattern (e.g. '4 2').

AreaStackedMarkStyle

Authored overlay for AreaStackedMarkStyle. Stacked / streamgraph area recipe override: solid fill + perimeter stroke.

Field	Type	Optional	Description
opacity	float	✓	Area fill opacity (0–1) for the stacked recipe.
stroke	StrokeStyle	✓	Perimeter stroke style for the stacked recipe.
halo_multiplier	float	✓	Halo stroke width multiplier for the stacked recipe; 0 disables the halo.

SliceLabelsStyle

Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offsets for per-slice text.

Field	Type	Optional	Description
offset	float	✓	Radial offset of slice labels from the arc in pixels.
line_height	float	✓	Line height for slice labels in pixels. Reserved vertical space above the disk is line_height × <rendered lines> per row, so the same value handles 1-line, 2-line, and multi-line templates.
font	FontStyle	✓	Slice label font style overrides. color only takes effect on single-series pies (no color: channel authored); multi-series pies always paint each label the dark companion of its own wedge color and ignore an authored color here. Unset fields fall back to style.charts.font (except color).
default_template	LabelsDefaultTemplate	✓	Default Jinja templates for per-slice labels when template is not authored.
template	str	✓	Jinja2 label template. Overrides default_template when authored.
where	str	✓	Jinja2 boolean filter — labels only render on rows where this is truthy.

TableRowRoleStyle

Authored overlay for TableRowRoleStyle.

Field	Type	Optional	Description
rule_width	float	✓	Rule width above rows with this role in pixels.
font	FontStyle	✓	Per-role font style override; None uses the default row font.
background	str	✓	Per-role row background color; None means no override.

SparkBarLabelStyle

Authored overlay for SparkBarLabelStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the spark bar label in pixels.
fill	str	✓	Label text fill color.
fill_opacity	float	✓	Label text fill opacity (0–1).
min_size	float	✓	Minimum bar fill width required to show the label in pixels.
height_offset	float	✓	Vertical offset of the label from its bar top in pixels.

DetailsArrowFontStyle

Authored overlay for DetailsArrowFontStyle. Font style for the expand/collapse arrow glyph.

Field	Type	Optional	Description
size	float	✓	Font size of the arrow glyph in pixels.

ScaleLogStyle

Authored overlay for ScaleLogStyle. Log-scale-only param.

Field	Type	Optional	Description
base	float	✓	Log base; only meaningful with type: log. None lets Vega-Lite apply its own default (10).

ScalePowStyle

Authored overlay for ScalePowStyle. Power-scale-only param.

Field	Type	Optional	Description
exponent	float	✓	Power exponent; only meaningful with type: pow. None uses Vega-Lite's default.

ScaleSymlogStyle

Authored overlay for ScaleSymlogStyle. Symlog-scale-only param.

Field	Type	Optional	Description
constant	float	✓	Symlog constant; only meaningful with type: symlog. None uses Vega-Lite's default.

LabelsDefaultTemplate

Authored overlay for LabelsDefaultTemplate. Default Jinja templates for per-slice pie/donut labels.

Field	Type	Optional	Description
with_color	str	✓	Default per-slice label template when the chart has a color binding.
no_color	str	✓	Default per-slice label template when the chart has no color binding.

PostgresSourceConfig

Postgres source configuration.

Field	Type	Optional	Description
type	enum: "postgres"		Source type identifier.
host	str		Database host name or IP address.
dbname	str		Database name (dbt accepts database as an input alias).
user	str		Database user name.
password	str		Database password (dbt accepts pass as an input alias).
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
port	int	✓	Database port number.
schema	str	✓	Default schema for queries.
connect_timeout	int	✓	Connection timeout in seconds.
role	str	✓	PostgreSQL role to assume after connecting.
search_path	str	✓	PostgreSQL search_path for the connection.
keepalives_idle	int	✓	Idle seconds before TCP keepalives begin.
sslmode	enum: "disable", "allow", "prefer", "require", "verify-ca", "verify-full"	✓	libpq SSL mode forwarded to psycopg2. None lets libpq decide its default.
sslcert	str	✓	Path to the client SSL certificate.
sslkey	str	✓	Path to the client SSL private key.
sslrootcert	str	✓	Path to the trusted SSL certificate authority file.
application_name	str	✓	Application name reported to PostgreSQL.
retries	int	✓	Number of connection retry attempts.

SnowflakeSourceConfig

Snowflake source configuration.

Field	Type	Optional	Description
type	enum: "snowflake"		Source type identifier.
account	str		Snowflake account identifier (e.g. xy12345.us-east-1).
database	str		Snowflake database name.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
user	str	✓	Snowflake user name. Omit for token-based authentication when supported.
password	str	✓	Snowflake password. Omit when using OAuth or key-pair auth.
warehouse	str	✓	Snowflake virtual warehouse name.
schema	str	✓	Default schema for queries.
role	str	✓	Snowflake role to assume for the session.
authenticator	str	✓	Snowflake authenticator name or external-browser mode.
private_key	str	✓	PEM private key used for key-pair authentication.
private_key_path	str	✓	Path to a PEM private key for key-pair authentication.
private_key_passphrase	str	✓	Passphrase for the configured private key.
token	str	✓	OAuth access token for token authentication.
oauth_client_id	str	✓	OAuth client identifier.
oauth_client_secret	str	✓	OAuth client secret.
query_tag	str	✓	Snowflake query tag applied to statements.
client_session_keep_alive	bool	✓	Whether Snowflake keeps the client session alive.
host	str	✓	Snowflake host override.
port	int	✓	Snowflake port override.
proxy_host	str	✓	HTTP proxy host for Snowflake connections.
proxy_port	int	✓	HTTP proxy port for Snowflake connections.
protocol	str	✓	Network protocol for the Snowflake connection.
connect_retries	int	✓	Number of retries while opening a connection.
connect_timeout	int	✓	Connection timeout in seconds.
retry_on_database_errors	bool	✓	Whether database errors are retried.
retry_all	bool	✓	Whether all connection errors are retried.
insecure_mode	bool	✓	Whether TLS certificate verification is disabled.
reuse_connections	bool	✓	Whether dbt reuses Snowflake connections.
s3_stage_vpce_dns_name	str	✓	Private VPC endpoint DNS name for S3 staging.
platform_detection_timeout_seconds	float	✓	Timeout for Snowflake platform detection.

BigQuerySourceConfig

BigQuery source configuration.

Field	Type	Optional	Description
type	enum: "bigquery"		Source type identifier.
project	str		GCP project ID.
dataset	str		BigQuery dataset name (equivalent to schema).
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
keyfile	str	✓	Path to service account JSON key file.
keyfile_json	dict[str, str | int | float | bool]	✓	Inline service account JSON dict.
location	str	✓	Dataset location (e.g. US, EU).
method	enum: "oauth", "oauth-secrets", "service-account", "service-account-json", "external-oauth-wif"	✓	dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise.
execution_project	str	✓	GCP project billed for BigQuery execution.
quota_project	str	✓	GCP project used for quota attribution.
api_endpoint	str	✓	BigQuery API endpoint override.
priority	enum: "interactive", "batch"	✓	BigQuery job priority.
maximum_bytes_billed	int	✓	Maximum bytes a BigQuery job may bill.
impersonate_service_account	str	✓	Service account to impersonate for BigQuery jobs.
job_retry_deadline_seconds	int	✓	Deadline in seconds for retrying a BigQuery job.
job_retries	int	✓	Number of BigQuery job retry attempts (dbt accepts retries as an input alias).
job_creation_timeout_seconds	int	✓	Timeout in seconds while creating a BigQuery job.
job_execution_timeout_seconds	int	✓	Timeout in seconds while executing a BigQuery job.
token	str	✓	OAuth access token.
refresh_token	str	✓	OAuth refresh token.
client_id	str	✓	OAuth client identifier.
client_secret	str	✓	OAuth client secret.
token_uri	str	✓	OAuth token endpoint URI.
workload_pool_provider_path	str	✓	Workload identity pool provider resource path.
service_account_impersonation_url	str	✓	Service-account impersonation endpoint URL.
token_endpoint	dict[str, str]	✓	OAuth token endpoint configuration.
compute_region	str	✓	Dataproc compute region.
dataproc_cluster_name	str	✓	Dataproc cluster name.
gcs_bucket	str	✓	Cloud Storage bucket for Dataproc submission.
submission_method	str	✓	dbt-bigquery Dataproc submission method.
dataproc_batch	dict[str, str | int | float | bool]	✓	Dataproc batch configuration.
scopes	list[str]	✓	OAuth scopes requested for BigQuery credentials.

RedshiftSourceConfig

Redshift source configuration.

Field	Type	Optional	Description
type	enum: "redshift"		Source type identifier.
host	str		Redshift cluster host name.
dbname	str		Redshift database name (dbt accepts database as an input alias).
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
port	int	✓	Redshift port number.
schema	str	✓	Default schema for queries.
user	str	✓	Redshift user name. Omit for IAM-based authentication when supported.
password	str	✓	Redshift password. Omit for IAM-based authentication when supported.
method	str	✓	Redshift authentication method.
cluster_id	str	✓	Redshift cluster identifier for IAM authentication.
iam_profile	str	✓	IAM profile ARN used for Redshift authentication.
autocreate	bool	✓	Whether dbt may create the database user.
db_groups	list[str]	✓	Redshift database groups assigned to the user.
ra3_node	bool	✓	Whether the target uses Redshift RA3 nodes.
connect_timeout	int	✓	Connection timeout in seconds.
role	str	✓	IAM role ARN used for Redshift operations.
sslmode	str	✓	SSL verification mode for the Redshift connection.
retries	int	✓	Number of Redshift connection retry attempts.
retry_all	bool	✓	Whether all connection errors are retried.
region	str	✓	AWS region containing the Redshift target.
access_key_id	str	✓	AWS access key identifier.
secret_access_key	str	✓	AWS secret access key.
idc_region	str	✓	AWS IAM Identity Center region.
issuer_url	str	✓	Identity-provider issuer URL.
idp_listen_port	int	✓	Local port used for identity-provider callbacks.
idc_client_display_name	str	✓	IAM Identity Center client display name.
idp_response_timeout	int	✓	Identity-provider response timeout in seconds.
token_endpoint	dict[str, str]	✓	Identity-provider token endpoint configuration.
is_serverless	bool	✓	Whether the target is Redshift Serverless.
serverless_work_group	str	✓	Redshift Serverless workgroup name.
serverless_acct_id	str	✓	AWS account identifier for Redshift Serverless.
tcp_keepalive	bool	✓	Whether TCP keepalives are enabled.
tcp_keepalive_idle	int	✓	Idle seconds before TCP keepalives begin.
tcp_keepalive_interval	int	✓	Seconds between TCP keepalive probes.
tcp_keepalive_count	int	✓	Number of TCP keepalive probes before failure.

MySQLSourceConfig

MySQL source configuration.

Field	Type	Optional	Description
type	enum: "mysql"		Source type identifier.
host	str		MySQL host name or IP address.
database	str		MySQL database name.
user	str		MySQL user name.
password	str		MySQL password.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
port	int	✓	MySQL port number.
schema	str	✓	Default schema for queries.

DuckDBSourceConfig

DuckDB source configuration.

Field	Type	Optional	Description
type	enum: "duckdb"		Source type identifier.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
max_query_duration_seconds	int	✓	Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source.
path	str	✓	DuckDB file path or ':memory:' for an in-memory database.
schema	str	✓	Default schema for unqualified table names (sets search_path).
duckdb_config	dict[str, str | int | float | bool]	✓	DuckDB connection configuration values, such as enable_external_access.
extensions	list[str | dict[str, str]]	✓	DuckDB extensions to install and load.
settings	dict[str, str | int | float | bool]	✓	DuckDB settings and pragma values.
secrets	list[dict[str, str | int | float | bool]]	✓	DuckDB secret definitions for external services.
external_root	str	✓	Root path for dbt-duckdb external materializations.
use_credential_provider	str	✓	Credential-provider chain used for external services.
attach	list[DuckDBAttachmentConfig]	✓	Databases to attach to the DuckDB connection.
filesystems	list[dict[str, str | int | float | bool]]	✓	fsspec filesystem configurations attached to DuckDB.
remote	DuckDBRemoteConfig	✓	Remote DuckDB connection configuration.
plugins	list[DuckDBPluginConfig]	✓	dbt-duckdb plugin configurations.
disable_transactions	bool	✓	Whether dbt-duckdb disables statement transactions.
keep_open	bool	✓	Whether dbt-duckdb keeps its connection open.
module_paths	list[str]	✓	Python module paths dbt-duckdb loads.
retries	DuckDBRetriesConfig	✓	dbt-duckdb connection and query retry configuration.
is_ducklake	bool	✓	Whether this source uses DuckLake.

SQLiteSourceConfig

SQLite source configuration.

Field	Type	Optional	Description
type	enum: "sqlite"		Source type identifier.
path	str		Path to the SQLite database file.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.

CsvSourceConfig

CSV file source configuration.

Field	Type	Optional	Description
type	enum: "csv"		Source type identifier.
files	dict[str, str]		Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using * (matches within a directory) and ? (matches one character). A glob must match at least one file; all matched files must share the same column schema and are concatenated into one table. The fan-out limit is execution.max_glob_file_count in dbt_charts.yml (default 1000). Required and must not be empty.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
delimiter	str	✓	Field delimiter character.
encoding	str	✓	File encoding.

ParquetSourceConfig

Parquet file source configuration.

Field	Type	Optional	Description
type	enum: "parquet"		Source type identifier.
files	dict[str, str]		Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using * (matches within a directory) and ? (matches one character). A glob must match at least one file; all matched files must share the same column schema and are concatenated into one table. The fan-out limit is execution.max_glob_file_count in dbt_charts.yml (default 1000). Required and must not be empty.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.

JsonSourceConfig

JSON file source configuration.

Field	Type	Optional	Description
type	enum: "json"		Source type identifier.
files	dict[str, str]		Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using * (matches within a directory) and ? (matches one character). A glob must match at least one file and all matched files are concatenated into one table. The fan-out limit is execution.max_glob_file_count in dbt_charts.yml (default 1000). Required and must not be empty.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
union_by_name	bool	✓	When True, rows from different files in a glob set are unified by column name: columns absent in a particular file are filled with NULL. When False (default), all files in a glob set must share the same column schema — a mismatch raises an error.

HttpSourceConfig

HTTP/REST API source configuration.

Field	Type	Optional	Description
type	enum: "http"		Source type identifier.
url	str		Base URL for HTTP requests.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
headers	dict[str, str]	✓	Default HTTP headers (e.g. Authorization).

DbtProfileSourceConfig

Reference to a dbt profile.

Field	Type	Optional	Description
type	enum: "dbt_profile"		Source type identifier.
profile	str		dbt profile name from profiles.yml.
cache	Cache	✓	Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out.
attribution	dict[str, str]	✓	Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity.
target	str	✓	dbt target to use; defaults to the profile's default target.
profiles_dir	str	✓	Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt.

VariableRef

Cross-file variable reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.variables.<name>'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically.

QueryRef

Cross-file query reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.queries.<name>'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically.

ChartRef

Cross-file chart reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.charts.<name>'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically.